Slicer Wiki - User contributions [en]

Documentation/Nightly/SlicerApplication/ExtensionsManager

2014-07-23T17:15:24Z

Matthew.woehlke: /* Extensions Manager */

<noinclude>{{documentation/versioncheck}}</noinclude>
__TOC__

3D Slicer now supports plug-ins which we call extensions. Extensions are available from an extension server. This allows end-users to select the extensions useful to them, without having to download the entire extension archive.

= Extensions Manager =

[[File:Extension_Manager.png|700px]]

== Prerequisites ==
ExtensionsManager must be enabled in the Application Settings (menu item "Edit -> Application Settings -> Extensions"). If you changed the setting, Slicer has to be restarted for it to become effective.
[[Image:ExtensionsManager-enable.png|Enable ExtensionsManager]]

== Installing an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:ExtensionsManager-4.1-Install_1a_extension_list.png|2. Choose an extension
File:ExtensionsManager-4.1-Install_1_extension_details.png|3. Look at extension details
File:ExtensionsManager-4.1-Install_2a_InstallButton.png.jpg|4. Click on "Install"
File:ExtensionsManager-4.1-Install_2b_ExtensionInstalled_ManagerAndInstallWidget.jpg|5. Extension is installed
File:ExtensionsManager-4.1-Install_Restart.jpg|6. Restart Slicer
File:ExtensionsManager-4.1-Install_3_ExtensionAvailable.jpg|7. Extension is available
</gallery>

== Installing an extension without network connection ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:TBD|2. Select 'Install from File' from the tools menu
File:TBD|3. Select a previously downloaded or othwerwise obtained extension archive
File:TBD|4. Extension is installed
File:TBD|5. Restart Slicer
File:ExtensionsManager-4.1-Install_3_ExtensionAvailable.jpg|6. Extension is available
</gallery>

== Uninstalling an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:ExtensionsManager-4.1-Uninstall_1b_UninstallButton.jpg|2. Click on "Uninstall"
File:ExtensionsManager-4.1-Uninstall_2_ScheduledForUninstall.jpg|3. Extension is scheduled for uninstall
File:ExtensionsManager-4.1-Uninstall_3_Restart.jpg|4. Restart Slicer
File:ExtensionsManager-4.1-Uninstall_4_ExtensionUninstalled.png| 5. Extension has been uninstalled
</gallery>

== Disabling an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:ExtensionsManager-4.1-Disable_1.png|2. Disable extension
File:ExtensionsManager-4.1-Disable_2.png|3. Restart Slicer
</gallery>

== Incompatible extensions ==

'''Caveat''': Considering that installed extensions are common to all Slicer version installed by a given user and that an extension is specific to a given revision of Slicer, it's currently not possible to have working extension installed for multiple version of Slicer. The issues has been reported as #[http://www.na-mic.org/Bug/view.php?id=1958 1958] and is currently targeted for 4.2.0 release.

<gallery widths=230px heights=120px perrow=4>
File:ExtensionsManager-4.1-IncompatibleExtension.jpg| Incompatible extension has been identified
File:ExtensionsManager-4.1-IncompatibleExtension_ErrorLogMessage.png | Error log message
</gallery>

== Extensions Manager Settings ==

=== Extensions settings ===
{|
| <gallery widths=400px heights=230px perrow=1>
File:ExtensionsManager-4.1-UnderTheHood_1_ExtensionsSettings.png|Extensions settings
</gallery>
||
# Extensions server URL: Address of the server used to download and install extensions
# Extensions installation path: Directory where extension packages should be extracted and installed
|}

=== Module settings ===
{|
| <gallery widths=400px heights=230px perrow=1>
File:ExtensionsManager-4.1-UnderTheHood_2_ModulesSettings.png|Module settings
</gallery>
||
# After installing an extension, the directories containing the modules bundled within an extension will be visible as additional module paths.
# Modules associated with an extension can also be disabled one by one.
|}

=== Launcher settings ===
{|
| <gallery widths=400px heights=230px perrow=1>
File:ExtensionsManager-4.1-UnderTheHood_3_LauncherSettings.png|Launcher settings
</gallery>
||
Whereas the module path is used to indicate Slicer where to look to load additional modules, the extension manager also takes care of updating the <code>LibraryPaths</code> / <code>Paths</code> / <code>EnvironmentVariables</code> in the launcher settings so that libraries associated with modules can be successfully loaded.
|}

{{:Documentation/{{documentation/version}}/FAQ/Extensions|Extensions}}

Documentation/Nightly/SlicerApplication/ExtensionsManager

2014-07-23T17:12:46Z

Matthew.woehlke: /* Installing an extension without network connection */

<noinclude>{{documentation/versioncheck}}</noinclude>
__TOC__

3D Slicer now supports plug-ins which we call extensions. Extensions are available from an extension server. This allows end-users to select the extensions useful to them, without having to download the entire extension archive.

= Extensions Manager =

[[File:Extension_Manager.png|700px]]

== Prerequisites ==
ExtensionsManager must be enabled in the Application Settings (menu item "Edit -> Application Settings -> Extensions"). If you changed the setting, Slicer has to be restarted for it to become effective.
[[Image:ExtensionsManager-enable.png|Enable ExtensionsManager]]

== Installing an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:ExtensionsManager-4.1-Install_1a_extension_list.png|2. Choose an extension
File:ExtensionsManager-4.1-Install_1_extension_details.png|3. Look at extension details
File:ExtensionsManager-4.1-Install_2a_InstallButton.png.jpg|4. Click on "Install"
File:ExtensionsManager-4.1-Install_2b_ExtensionInstalled_ManagerAndInstallWidget.jpg|5. Extension is installed
File:ExtensionsManager-4.1-Install_Restart.jpg|6. Restart Slicer
File:ExtensionsManager-4.1-Install_3_ExtensionAvailable.jpg|7. Extension is available
</gallery>

== Installing an extension without network connection ==

== Installing an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:TBD|2. Select 'Install from File' from the tools menu
File:TBD|3. Select a previously downloaded or othwerwise obtained extension archive
File:TBD|4. Extension is installed
File:TBD|5. Restart Slicer
File:ExtensionsManager-4.1-Install_3_ExtensionAvailable.jpg|6. Extension is available
</gallery>

== Uninstalling an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:ExtensionsManager-4.1-Uninstall_1b_UninstallButton.jpg|2. Click on "Uninstall"
File:ExtensionsManager-4.1-Uninstall_2_ScheduledForUninstall.jpg|3. Extension is scheduled for uninstall
File:ExtensionsManager-4.1-Uninstall_3_Restart.jpg|4. Restart Slicer
File:ExtensionsManager-4.1-Uninstall_4_ExtensionUninstalled.png| 5. Extension has been uninstalled
</gallery>

== Disabling an extension ==

<gallery widths=230px heights=230px perrow=4>
File:ExtensionsManager-4.1-Install_0_ExtensionsManagerMenu.jpg|1. Open extensions manager
File:ExtensionsManager-4.1-Disable_1.png|2. Disable extension
File:ExtensionsManager-4.1-Disable_2.png|3. Restart Slicer
</gallery>

== Incompatible extensions ==

'''Caveat''': Considering that installed extensions are common to all Slicer version installed by a given user and that an extension is specific to a given revision of Slicer, it's currently not possible to have working extension installed for multiple version of Slicer. The issues has been reported as #[http://www.na-mic.org/Bug/view.php?id=1958 1958] and is currently targeted for 4.2.0 release.

<gallery widths=230px heights=120px perrow=4>
File:ExtensionsManager-4.1-IncompatibleExtension.jpg| Incompatible extension has been identified
File:ExtensionsManager-4.1-IncompatibleExtension_ErrorLogMessage.png | Error log message
</gallery>

== Extensions Manager Settings ==

=== Extensions settings ===
{|
| <gallery widths=400px heights=230px perrow=1>
File:ExtensionsManager-4.1-UnderTheHood_1_ExtensionsSettings.png|Extensions settings
</gallery>
||
# Extensions server URL: Address of the server used to download and install extensions
# Extensions installation path: Directory where extension packages should be extracted and installed
|}

=== Module settings ===
{|
| <gallery widths=400px heights=230px perrow=1>
File:ExtensionsManager-4.1-UnderTheHood_2_ModulesSettings.png|Module settings
</gallery>
||
# After installing an extension, the directories containing the modules bundled within an extension will be visible as additional module paths.
# Modules associated with an extension can also be disabled one by one.
|}

=== Launcher settings ===
{|
| <gallery widths=400px heights=230px perrow=1>
File:ExtensionsManager-4.1-UnderTheHood_3_LauncherSettings.png|Launcher settings
</gallery>
||
Whereas the module path is used to indicate Slicer where to look to load additional modules, the extension manager also takes care of updating the <code>LibraryPaths</code> / <code>Paths</code> / <code>EnvironmentVariables</code> in the launcher settings so that libraries associated with modules can be successfully loaded.
|}

{{:Documentation/{{documentation/version}}/FAQ/Extensions|Extensions}}

Documentation/Nightly/Developers/ExtensionWizard

2014-06-17T16:56:57Z

Matthew.woehlke: /* Requirements */ update wording, external links for improved consistency

== 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 ===

[[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 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 [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 ====

Git is available via [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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).

=== 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 '<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 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
<nowiki/>
# 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
<nowiki/>
# 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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[Documentation/{{documentation/version}}/Developers/Modules|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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
slicerExtensionWizard --templatePath ~/code/Templates
<nowiki/>
# 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:

# 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
<nowiki/>
# 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 [[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:

# "Publish" your extension by making it available on a publicly accessible repository.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''

{{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:

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.

{{notice|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
<nowiki/>
# 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.

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

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.

Documentation/Nightly/Developers/Style Guide

2014-06-09T18:44:26Z

Matthew.woehlke: /* Wiki */

<noinclude>{{documentation/versioncheck}}</noinclude>
= Code style =

'''Code that inherits from VTK classes should follow VTK coding conventions for naming, indentation, etc.''' See http://www.vtk.org/Wiki/VTK_Coding_Standards for details.

== Naming ==

# Acronyms should be written with the same case for each letter (all uppercase or all lowercase).
#: ''RASToSlice'' not ''RasToSlice''
#: ''vtkMRML'' not ''vtkMrml''
#: ''vtkSlicer'' not ''vTKSlicer''
# Words should be spelled out and not abreviated
#: ''GetWindow'' not ''GetWin''
# File names must follow the [http://en.wikipedia.org/wiki/CamelCase Camel case] convention
#: ''TestMyFeature.cxx'' not ''Test-My_Feature.cxx''
# Use US English words and spelling
#: "Millimeter" not "Millimetre"
#: "Color" not "Colour"

== Comments ==

# include extensive comments in the header files
# keep the comments up to date as the code changes
# use the keyword <code>\todo</code> to flag spots in the code that need to be revisited
# do not leave blocks of commented out code in the source file -- if needed insert links to prior svn versions as comments

== Functions ==
# Don't mix different levels of abstraction
#: Examples:
#:: When dealing with files names and path, use [http://vtk.org/gitweb?p=VTK.git;a=blob;f=Utilities/KWSys/vtksys/SystemTools.hxx.in;h=04f197842695c5914d1a49d4738159d3bccb08e8;hb=HEAD kwsys::SystemTools] in VTK classes, [http://doc.qt.nokia.com/{{documentation/{{documentation/version}}/qtversion}}/qfileinfo.html QFileInfo]/[http://doc.qt.nokia.com/{{documentation/{{documentation/version}}/qtversion}}/qdir.html QDir] in Qt classes or [http://docs.python.org/library/os.path.html os.path] in python. Instead of doing string manipulation manually:
#:::<code>QString filePath = directoryPath + "/" + fileName + ".exe"</code>)
#:: prefer instead:
#:::<code>SystemTools::JoinPath(), SystemTools::GetFilenameName()...</code>
#:::<code>QFileInfo(QDir directory, QString fileName), QFileInfo::suffix(), QFileInfo::absoluteFilePath()...</code>
#:::<code>os.path.join(), os.path.splitext(), os.path.abspath()...</code>
#: References:
#:* [http://www.amazon.com/gp/product/0132350882?ie=UTF8&tag=solisyntprog-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=0132350882 Clean Code] from ''Robert C. Martin'': ''Mixing levels of abstraction within a function is always confusing. Readers may not be able to tell whether a particular expression is an essential concept or a detail. Worse, like broken windows, once details are mixed with essential concepts, more and more details tend to accrete within the functions.''
#:* http://zuskin.com/coding_habits__functions.htm#Abstraction_levels
# Use STL where you can, but follow the VTK [http://www.vtk.org/Wiki/VTK_FAQ#Can_I_use_STL_with_VTK.3F guidelines]
## However, prefer [http://doc.qt.nokia.com/{{documentation/{{documentation/version}}/qtversion}}/containers.html Qt Container classes] to STL classes in Qt files
## Note that a [http://www.vtk.org/doc/nightly/html/classvtkCollection.html vtkCollection] is somewhat equivalent to <code>std::list<vtkSmartPointer<vtkObject*> ></code>

== Layout ==
=== Includes ===
# Only include the necessary files, no more.
# Group includes per library
# Alphabetically sort files within groups
# Order groups from local to global
#: e.g. Module then MRML then CTK then Qt then VTK then ITK then STL
# Implementation files should include the header files first
For example:
// header
// ...
// end header

#include "qSlicerMyModule.h"

// MyModule includes
#include "qSlicerMyModuleWidget.h"
#include "vtkSlicerMyModuleLogic.h"

// MRML includes
#include "vtkMRMLScene.h"

// Qt includes
#include <QDialog>

// VTK includes
#include <vtkSmartPointer.h>

// STD includes
#include <vector>

== Language Specific ==

# [[Documentation/{{documentation/version}}/Developers/Style Guide/Cpp | C++]]
# [[Documentation/{{documentation/version}}/Developers/Style Guide/Python | Python]]
# [[Documentation/{{documentation/version}}/Developers/Style Guide/CMake | CMake]]

== Library Dependencies ==

# MRML classes should only depend on vtk and itk (not Slicer Logic or Qt)
# Logic classes depend on MRML to store state
# Logic classes should encapsulate vtk and itk pipelines to accomplish specific slicer tasks (such as resampling volumes for display)
# GUI classes can depend on MRML and Logic and Qt

== Development Practices ==

# While developing code, enable VTK_DEBUG_LEAKS (ON by default) in your vtk build and be sure to clean up any leaks that arise from your contributions.

== Coordinate Systems ==

# World space for 3D Views is in RAS (Right Anterior Superior) space. See [[Coordinate systems]].
# All units are expressed in Millimeters (mm)

== Error and warning messages ==
{| width="100%"
| valign="top"|
The ITK, VTK, Qt, std::cout, std::cerr .. all appear in the error log and can easily be filtered according to their type (debug/warning/error).

* '''Errors''': Error should be used to signal something that should not happen. They usually mean that the execution of the current function/code should be stopped.
* '''Warnings''': Warning should be used to signal potentially dangerous behavior. Also consider using these in deprecated methods to warn your fellow developers.
* '''Debugs''': For general debug and developer aimed information, one can use the debug messages.

| align="right"|
|[[Image: Slicer4ErrorLog.jpg|thumb|200px| Error log in Slicer 4]]
|}

* In Qt-based classes:
** For error messages, use [http://qt-project.org/doc/qt-4.8/qtglobal.html#qCritical qCritical()].
if (somethingWrongHappened)
{
qCritical() << "I encountered an error";
return;
}

:* For warnings, use [http://qt-project.org/doc/qt-4.8/qtglobal.html#qWarning qWarning()].
qWarning() << "Be careful here, this is dangerous";

:* For debug, use [http://qt-project.org/doc/qt-4.8/qtglobal.html#qDebug qDebug()]:
qDebug() << "This variable has the value: "<< value;

* In VTK-based classes:
** For error messages, use [http://www.vtk.org/doc/release/3/html/vtkSetGet_8h.html vtkErrorMacro()].
if (somethingWrongHappened)
{
vtkErrorMacro("I encountered an error");
return;
}

:* For warnings, use [http://www.vtk.org/doc/release/3/html/vtkSetGet_8h.html vtkWarningMacro()].
vtkWarningMacro("Be careful here, this is dangerous");

:* For debug, use [http://www.vtk.org/doc/release/3/html/vtkSetGet_8h.html vtkDebugMacro()]:
vtkDebugMacro("This variable has the value: "<< value);

== Misc. ==
# No more than 80 characters per line

= Commits =
==Summary==
#Prefix the commit message title with "BUG:","ENH:","COMP:", "STYLE:". Note the ':' (colon) character.
#Explain in the commit message title the "impact of the commit to the user"
#Add in the commit message body the Mantis issue number prefixed by '#' (pound) character.

==Commit message prefix==
Subversion Commits to Slicer require commit type in the comment.

Valid commit types are:
BUG: - a change made to fix a runtime issue
(crash, segmentation fault, exception, or incorrect result,
COMP: - a fix for a compilation issue, error or warning,
ENH: - new functionality added to the project,
PERF: - a performance improvement,
STYLE: - a change that does not impact the logic or execution of the code.
(improve coding style, comments, documentation).
Note that the ':'(colon) directly follows the commit tag. For example, it is: "STYLE:" not "STYLE :"

The Subversion command to commit the change is:
svn commit -m "BUG: fixed core dump when passed float data" filename1[, filename2, ...]

By using the <code>-m</code> command line option, it's not possible to submit a message having multiple line.
Submitting a mutli-line message can be achieved using the <code>-f</code> option:
svn commit -f /path/to/message filename1[, filename2, ...]

It's also possible to set the environment variable [http://www.google.com/search?q=SVN_EDITOR|<code>SVN_EDITOR</code>]

==Message content==
# A good commit message title (first line) should '''explain what the commit does for the user, not ''how'' it is done'''. ''How'' can be explained in the body of the commit message (if looking at the code of the commit is not self explanatory enough).
#: Examples:
#:* Bad: <code>BUG: Check pointer validity before dereferencing</code> -> ''implementation detail'', ''self-explanatory'' (by looking at the code)
#:* Good: <code>BUG: Fix crash in Module X when clicking Apply button</code>
#:* Bad: <code>ENH: More work in qSlicerXModuleWidget</code> -> <code>more work</code> is ''too vague'', <code>qSlicerXModuleWidget</code> is too ''low level''
#:* Good: <code>ENH: Add float image outputs in module X</code>
#:* Bad: <code>COMP: Typo in cmake variable</code> -> ''implementation detail'', ''self-explanatory''
#:* Good: <code>COMP: Fix compilation error with Numpy on Visual Studio</code>
# If the commit is related to a [http://na-mic.org/Mantis/view_all_bug_page.php mantis issue] (bug or feature request), you can mention it in the commit message body by preceding the issue number with a '''#'''(pound) character:
BUG: Fix crash in Volume Rendering module when switching view layout

vtkSetAndObserveMRMLNodeEventsMacro can't be used for observing all types of vtkObjects,
only vtkMRMLNode is expected by vtkMRMLAbstractLogic::OnMRMLNodeModified(...)
Closes #1641
Where <code>1641</code> refers to the [http://www.na-mic.org/Bug/view.php?id=1641 issue number] in mantis.

# Notice the empty 2nd line.

==Importing changes from external project/repository==
When you update the git tag or svn revision of any external project, explicit in the commit message what the update does instead of just mentioning that an update in made.

This will avoid having a Slicer commit history made of ineligible messages:
r19180 - ENH: Update git tag
r19181 - BUG: Update svn revision
r19182 - ENH: revision updated
...

Ideally it should be the same message than the commit(s) in the external repository.

Example:
<code>ENH: Add feature A in module X</code> instead of <code>ENH: Update git tag</code>

== Resources ==
http://www.na-mic.org/Wiki/index.php/Engineering:Subversion_Repository

http://www.slicer.org/slicerWiki/index.php/Slicer:git-svn

= UI Design Guidelines =
{{:Documentation/{{documentation/version}}/Developers/Style Guide/UI}}

= Logging =

In VTK classes:
* vtkErrorMacro("vtkMRMLClipModelsNode:: Invalid Clip Type");
* vtkWarningMacro("Model " << modelNode->GetName() << "'s display node is null\n");
* vtkDebugMacro("CreateWidget: found a glyph type already defined for this node: " << iter->second);

In QT classes:
* qCritical() << "qSlicerUtils::setPermissionsRecursively: Failed to set permissions on file" << info.filePath();
* qWarning() << "qSlicerIOManager::openScreenshotDialog: Unable to get Annotations module (annotations), using the CTK screen shot dialog.";
* qDebug() << "qMRMLSceneFactoryWidget::deleteNode(" <<className <<") no node";

= Wiki =

* Prefer to follow [http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_(capitalization) Wikipedia conventions] for page naming: ''For multiword page titles, leave the second and subsequent words in lowercase unless the title phrase is a proper noun that would always occur capitalized, even in the middle of a sentence''.
* Versioned pages should include '<nowiki><noinclude>{{documentation/versioncheck}}</noinclude></nowiki>' at the very beginning.
** FAQ pages should also have (immediately after the above): '<nowiki><noinclude>__TOC__={{#titleparts: {{PAGENAME}} | | -1 }}=</noinclude><includeonly>='''</nowiki>''name of parent FAQ''<nowiki>: {{{1}}}'''=</includeonly></nowiki> (be sure to replace "''name of parent FAQ''").

Documentation/Nightly/Developers/Style Guide

2014-06-09T18:37:24Z

Matthew.woehlke: add wiki style section

<noinclude>{{documentation/versioncheck}}</noinclude>
= Code style =

'''Code that inherits from VTK classes should follow VTK coding conventions for naming, indentation, etc.''' See http://www.vtk.org/Wiki/VTK_Coding_Standards for details.

== Naming ==

# Acronyms should be written with the same case for each letter (all uppercase or all lowercase).
#: ''RASToSlice'' not ''RasToSlice''
#: ''vtkMRML'' not ''vtkMrml''
#: ''vtkSlicer'' not ''vTKSlicer''
# Words should be spelled out and not abreviated
#: ''GetWindow'' not ''GetWin''
# File names must follow the [http://en.wikipedia.org/wiki/CamelCase Camel case] convention
#: ''TestMyFeature.cxx'' not ''Test-My_Feature.cxx''
# Use US English words and spelling
#: "Millimeter" not "Millimetre"
#: "Color" not "Colour"

== Comments ==

# include extensive comments in the header files
# keep the comments up to date as the code changes
# use the keyword <code>\todo</code> to flag spots in the code that need to be revisited
# do not leave blocks of commented out code in the source file -- if needed insert links to prior svn versions as comments

== Functions ==
# Don't mix different levels of abstraction
#: Examples:
#:: When dealing with files names and path, use [http://vtk.org/gitweb?p=VTK.git;a=blob;f=Utilities/KWSys/vtksys/SystemTools.hxx.in;h=04f197842695c5914d1a49d4738159d3bccb08e8;hb=HEAD kwsys::SystemTools] in VTK classes, [http://doc.qt.nokia.com/{{documentation/{{documentation/version}}/qtversion}}/qfileinfo.html QFileInfo]/[http://doc.qt.nokia.com/{{documentation/{{documentation/version}}/qtversion}}/qdir.html QDir] in Qt classes or [http://docs.python.org/library/os.path.html os.path] in python. Instead of doing string manipulation manually:
#:::<code>QString filePath = directoryPath + "/" + fileName + ".exe"</code>)
#:: prefer instead:
#:::<code>SystemTools::JoinPath(), SystemTools::GetFilenameName()...</code>
#:::<code>QFileInfo(QDir directory, QString fileName), QFileInfo::suffix(), QFileInfo::absoluteFilePath()...</code>
#:::<code>os.path.join(), os.path.splitext(), os.path.abspath()...</code>
#: References:
#:* [http://www.amazon.com/gp/product/0132350882?ie=UTF8&tag=solisyntprog-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=0132350882 Clean Code] from ''Robert C. Martin'': ''Mixing levels of abstraction within a function is always confusing. Readers may not be able to tell whether a particular expression is an essential concept or a detail. Worse, like broken windows, once details are mixed with essential concepts, more and more details tend to accrete within the functions.''
#:* http://zuskin.com/coding_habits__functions.htm#Abstraction_levels
# Use STL where you can, but follow the VTK [http://www.vtk.org/Wiki/VTK_FAQ#Can_I_use_STL_with_VTK.3F guidelines]
## However, prefer [http://doc.qt.nokia.com/{{documentation/{{documentation/version}}/qtversion}}/containers.html Qt Container classes] to STL classes in Qt files
## Note that a [http://www.vtk.org/doc/nightly/html/classvtkCollection.html vtkCollection] is somewhat equivalent to <code>std::list<vtkSmartPointer<vtkObject*> ></code>

== Layout ==
=== Includes ===
# Only include the necessary files, no more.
# Group includes per library
# Alphabetically sort files within groups
# Order groups from local to global
#: e.g. Module then MRML then CTK then Qt then VTK then ITK then STL
# Implementation files should include the header files first
For example:
// header
// ...
// end header

#include "qSlicerMyModule.h"

// MyModule includes
#include "qSlicerMyModuleWidget.h"
#include "vtkSlicerMyModuleLogic.h"

// MRML includes
#include "vtkMRMLScene.h"

// Qt includes
#include <QDialog>

// VTK includes
#include <vtkSmartPointer.h>

// STD includes
#include <vector>

== Language Specific ==

# [[Documentation/{{documentation/version}}/Developers/Style Guide/Cpp | C++]]
# [[Documentation/{{documentation/version}}/Developers/Style Guide/Python | Python]]
# [[Documentation/{{documentation/version}}/Developers/Style Guide/CMake | CMake]]

== Library Dependencies ==

# MRML classes should only depend on vtk and itk (not Slicer Logic or Qt)
# Logic classes depend on MRML to store state
# Logic classes should encapsulate vtk and itk pipelines to accomplish specific slicer tasks (such as resampling volumes for display)
# GUI classes can depend on MRML and Logic and Qt

== Development Practices ==

# While developing code, enable VTK_DEBUG_LEAKS (ON by default) in your vtk build and be sure to clean up any leaks that arise from your contributions.

== Coordinate Systems ==

# World space for 3D Views is in RAS (Right Anterior Superior) space. See [[Coordinate systems]].
# All units are expressed in Millimeters (mm)

== Error and warning messages ==
{| width="100%"
| valign="top"|
The ITK, VTK, Qt, std::cout, std::cerr .. all appear in the error log and can easily be filtered according to their type (debug/warning/error).

* '''Errors''': Error should be used to signal something that should not happen. They usually mean that the execution of the current function/code should be stopped.
* '''Warnings''': Warning should be used to signal potentially dangerous behavior. Also consider using these in deprecated methods to warn your fellow developers.
* '''Debugs''': For general debug and developer aimed information, one can use the debug messages.

| align="right"|
|[[Image: Slicer4ErrorLog.jpg|thumb|200px| Error log in Slicer 4]]
|}

* In Qt-based classes:
** For error messages, use [http://qt-project.org/doc/qt-4.8/qtglobal.html#qCritical qCritical()].
if (somethingWrongHappened)
{
qCritical() << "I encountered an error";
return;
}

:* For warnings, use [http://qt-project.org/doc/qt-4.8/qtglobal.html#qWarning qWarning()].
qWarning() << "Be careful here, this is dangerous";

:* For debug, use [http://qt-project.org/doc/qt-4.8/qtglobal.html#qDebug qDebug()]:
qDebug() << "This variable has the value: "<< value;

* In VTK-based classes:
** For error messages, use [http://www.vtk.org/doc/release/3/html/vtkSetGet_8h.html vtkErrorMacro()].
if (somethingWrongHappened)
{
vtkErrorMacro("I encountered an error");
return;
}

:* For warnings, use [http://www.vtk.org/doc/release/3/html/vtkSetGet_8h.html vtkWarningMacro()].
vtkWarningMacro("Be careful here, this is dangerous");

:* For debug, use [http://www.vtk.org/doc/release/3/html/vtkSetGet_8h.html vtkDebugMacro()]:
vtkDebugMacro("This variable has the value: "<< value);

== Misc. ==
# No more than 80 characters per line

= Commits =
==Summary==
#Prefix the commit message title with "BUG:","ENH:","COMP:", "STYLE:". Note the ':' (colon) character.
#Explain in the commit message title the "impact of the commit to the user"
#Add in the commit message body the Mantis issue number prefixed by '#' (pound) character.

==Commit message prefix==
Subversion Commits to Slicer require commit type in the comment.

Valid commit types are:
BUG: - a change made to fix a runtime issue
(crash, segmentation fault, exception, or incorrect result,
COMP: - a fix for a compilation issue, error or warning,
ENH: - new functionality added to the project,
PERF: - a performance improvement,
STYLE: - a change that does not impact the logic or execution of the code.
(improve coding style, comments, documentation).
Note that the ':'(colon) directly follows the commit tag. For example, it is: "STYLE:" not "STYLE :"

The Subversion command to commit the change is:
svn commit -m "BUG: fixed core dump when passed float data" filename1[, filename2, ...]

By using the <code>-m</code> command line option, it's not possible to submit a message having multiple line.
Submitting a mutli-line message can be achieved using the <code>-f</code> option:
svn commit -f /path/to/message filename1[, filename2, ...]

It's also possible to set the environment variable [http://www.google.com/search?q=SVN_EDITOR|<code>SVN_EDITOR</code>]

==Message content==
# A good commit message title (first line) should '''explain what the commit does for the user, not ''how'' it is done'''. ''How'' can be explained in the body of the commit message (if looking at the code of the commit is not self explanatory enough).
#: Examples:
#:* Bad: <code>BUG: Check pointer validity before dereferencing</code> -> ''implementation detail'', ''self-explanatory'' (by looking at the code)
#:* Good: <code>BUG: Fix crash in Module X when clicking Apply button</code>
#:* Bad: <code>ENH: More work in qSlicerXModuleWidget</code> -> <code>more work</code> is ''too vague'', <code>qSlicerXModuleWidget</code> is too ''low level''
#:* Good: <code>ENH: Add float image outputs in module X</code>
#:* Bad: <code>COMP: Typo in cmake variable</code> -> ''implementation detail'', ''self-explanatory''
#:* Good: <code>COMP: Fix compilation error with Numpy on Visual Studio</code>
# If the commit is related to a [http://na-mic.org/Mantis/view_all_bug_page.php mantis issue] (bug or feature request), you can mention it in the commit message body by preceding the issue number with a '''#'''(pound) character:
BUG: Fix crash in Volume Rendering module when switching view layout

vtkSetAndObserveMRMLNodeEventsMacro can't be used for observing all types of vtkObjects,
only vtkMRMLNode is expected by vtkMRMLAbstractLogic::OnMRMLNodeModified(...)
Closes #1641
Where <code>1641</code> refers to the [http://www.na-mic.org/Bug/view.php?id=1641 issue number] in mantis.

# Notice the empty 2nd line.

==Importing changes from external project/repository==
When you update the git tag or svn revision of any external project, explicit in the commit message what the update does instead of just mentioning that an update in made.

This will avoid having a Slicer commit history made of ineligible messages:
r19180 - ENH: Update git tag
r19181 - BUG: Update svn revision
r19182 - ENH: revision updated
...

Ideally it should be the same message than the commit(s) in the external repository.

Example:
<code>ENH: Add feature A in module X</code> instead of <code>ENH: Update git tag</code>

== Resources ==
http://www.na-mic.org/Wiki/index.php/Engineering:Subversion_Repository

http://www.slicer.org/slicerWiki/index.php/Slicer:git-svn

= UI Design Guidelines =
{{:Documentation/{{documentation/version}}/Developers/Style Guide/UI}}

= Logging =

In VTK classes:
* vtkErrorMacro("vtkMRMLClipModelsNode:: Invalid Clip Type");
* vtkWarningMacro("Model " << modelNode->GetName() << "'s display node is null\n");
* vtkDebugMacro("CreateWidget: found a glyph type already defined for this node: " << iter->second);

In QT classes:
* qCritical() << "qSlicerUtils::setPermissionsRecursively: Failed to set permissions on file" << info.filePath();
* qWarning() << "qSlicerIOManager::openScreenshotDialog: Unable to get Annotations module (annotations), using the CTK screen shot dialog.";
* qDebug() << "qMRMLSceneFactoryWidget::deleteNode(" <<className <<") no node";

= Wiki =

* Prefer to follow [http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_(capitalization) Wikipedia conventions] for page naming: ''For multiword page titles, leave the second and subsequent words in lowercase unless the title phrase is a proper noun that would always occur capitalized, even in the middle of a sentence''.

* Versioned pages should include '<nowiki><noinclude>{{documentation/versioncheck}}</noinclude></nowiki>' at the very beginning.

Documentation/Nightly/Developers/Build system/Qt resource files

2014-06-09T18:30:52Z

Matthew.woehlke: remove potentially confusing notice

<noinclude>{{documentation/versioncheck}}</noinclude>

== Generating QRC Files: genqrc.py ==

Slicer includes a tool to generate <code>.qrc</code> files from resource directories. This convenience tool was created to simplify working with icons, which can require several entries per icon (one per available resolution) that may be cumbersome to write by hand.

The script ([https://github.com/Slicer/Slicer/blob/master/Utilities/Scripts/genpy.py genpy.py]) can be found in the [https://github.com/Slicer/Slicer/tree/master/Utilities/Scripts Utilities/Scripts] directory of the Slicer source.

The positional argument(s) to the script give a list of directories that should be scanned for resource files (e.g. <code>'Icons'</code>). An optional <code>-o</code> parameter may be used to specify the output file (otherwise the script will print to stdout). The script should normally be run in the directory of the desired output <code>.qrc</code> file in order to provide and generate relative paths that will be both understood correctly by the Qt resource compiler, and meaningful to other developers' checkouts.

For example, to generate [https://github.com/Slicer/Slicer/blob/master/Base/QTGUI/Resources/qSlicerBaseQTGUI.qrc qSlicerBaseQTGUI.qrc], one would run:

cd /path/to/slicer/source
cd Base/QTGUI/Resources
../../../Utilities/Scripts/genqrc.py -o qSlicerBaseQTGUI.qrc Icons

This tool is currently meant to be used in an "offline" manner (i.e. not part of the build process). When adding icons, you should re-run the script to generate an updated <code>.qrc</code> file and commit the updated file.

Documentation/Nightly/Developers/Build system

2014-06-09T18:26:56Z

Matthew.woehlke:

<noinclude>{{documentation/versioncheck}}</noinclude>
Leveraging the [http://www.cmake.org/cmake/help/v2.8.8/cmake.html#module:ExternalProject ExternalProject] module provided by [[{{tool|logo|cmake}}|x16px]] [{{tool|homepage|cmake}} CMake], Slicer SuperBuild system allows developers to quickly install and configure the multiple open-source packages and libraries it depends on.

;[[Documentation/{{documentation/version}}/Developers/Versioning|Versioning]]
: Convention to name Slicer packages.

;[[Documentation/{{documentation/version}}/Developers/Factory|Factory description]]
: Current configuration of Slicer's factory machines.

;[[Documentation/{{documentation/version}}/Developers/Build_ExtensionsIndex|Build ExtensionsIndex]]
: How to build an ExtensionsIndex (collection of extension description files) ?

;[[Documentation/{{documentation/version}}/Developers/FactoryDashboardSetup |Factory Dashboard setup]]
: Provide a general overview of the slicer application and extensions dashboard script organization

;[[Documentation/{{documentation/version}}/Developers/Build system/Qt resource files|Qt resource files]]
: Describes the <code>genqrc.py</code> tool for automatic generation/updating of Qt resource scripts.

Documentation/Nightly/Developers/Build system/Qt resource files

2014-06-09T18:22:40Z

Matthew.woehlke: fix name of script in link (genpy s.b. genqrc)

<noinclude>{{documentation/versioncheck}}</noinclude>

== Generating QRC Files: genqrc.py ==

Slicer includes a tool to generate <code>.qrc</code> files from resource directories. This convenience tool was created to simplify working with icons, which can require several entries per icon (one per available resolution) that may be cumbersome to write by hand.

The script ([https://github.com/Slicer/Slicer/blob/master/Utilities/Scripts/genqrc.py genqrc.py]) can be found in the [https://github.com/Slicer/Slicer/tree/master/Utilities/Scripts Utilities/Scripts] directory of the Slicer source.

The positional argument(s) to the script give a list of directories that should be scanned for resource files (e.g. <code>'Icons'</code>). An optional <code>-o</code> parameter may be used to specify the output file (otherwise the script will print to stdout). The script should normally be run in the directory of the desired output <code>.qrc</code> file in order to provide and generate relative paths that will be both understood correctly by the Qt resource compiler, and meaningful to other developers' checkouts.

For example, to generate [https://github.com/Slicer/Slicer/blob/master/Base/QTGUI/Resources/qSlicerBaseQTGUI.qrc qSlicerBaseQTGUI.qrc], one would run:

cd /path/to/slicer/source
cd Base/QTGUI/Resources
../../../Utilities/Scripts/genqrc.py -o qSlicerBaseQTGUI.qrc Icons

{{notice|The list of resource directories in the generated <code>.qrc</code> is printed using Python's representational format of a list of strings, which is ''not'' suitable for feeding to the shell directly. You should perform the necessary syntax conversion by hand when running the script. (Usually it is sufficient to remove the square brackets and commas.)}}

This tool is currently meant to be used in an "offline" manner (i.e. not part of the build process). When adding icons, you should re-run the script to generate an updated <code>.qrc</code> file and commit the updated file.

Documentation/Nightly/Developers/Build system/Qt resource files

2014-06-09T18:21:22Z

Matthew.woehlke: Created page with '<noinclude>{{documentation/versioncheck}}</noinclude> == Generating QRC Files: genqrc.py == Slicer includes a tool to generate <code>.qrc</code> files from resource directories…'

<noinclude>{{documentation/versioncheck}}</noinclude>

== Generating QRC Files: genqrc.py ==

Slicer includes a tool to generate <code>.qrc</code> files from resource directories. This convenience tool was created to simplify working with icons, which can require several entries per icon (one per available resolution) that may be cumbersome to write by hand.

The script ([https://github.com/Slicer/Slicer/blob/master/Utilities/Scripts/genpy.py genpy.py]) can be found in the [https://github.com/Slicer/Slicer/tree/master/Utilities/Scripts Utilities/Scripts] directory of the Slicer source.

The positional argument(s) to the script give a list of directories that should be scanned for resource files (e.g. <code>'Icons'</code>). An optional <code>-o</code> parameter may be used to specify the output file (otherwise the script will print to stdout). The script should normally be run in the directory of the desired output <code>.qrc</code> file in order to provide and generate relative paths that will be both understood correctly by the Qt resource compiler, and meaningful to other developers' checkouts.

For example, to generate [https://github.com/Slicer/Slicer/blob/master/Base/QTGUI/Resources/qSlicerBaseQTGUI.qrc qSlicerBaseQTGUI.qrc], one would run:

cd /path/to/slicer/source
cd Base/QTGUI/Resources
../../../Utilities/Scripts/genqrc.py -o qSlicerBaseQTGUI.qrc Icons

{{notice|The list of resource directories in the generated <code>.qrc</code> is printed using Python's representational format of a list of strings, which is ''not'' suitable for feeding to the shell directly. You should perform the necessary syntax conversion by hand when running the script. (Usually it is sufficient to remove the square brackets and commas.)}}

This tool is currently meant to be used in an "offline" manner (i.e. not part of the build process). When adding icons, you should re-run the script to generate an updated <code>.qrc</code> file and commit the updated file.

Documentation/Nightly/Modules/ExtensionWizard

2014-06-04T21:21:30Z

Matthew.woehlke: Created page with '<noinclude>{{documentation/versioncheck}}</noinclude> {{documentation/{{documentation/version}}/module-header}} {{documentation/{{documentation/version}}/module-section|Introduc…'

<noinclude>{{documentation/versioncheck}}</noinclude>
{{documentation/{{documentation/version}}/module-header}}

{{documentation/{{documentation/version}}/module-section|Introduction and Acknowledgements}}
{{documentation/{{documentation/version}}/module-introduction-start|{{documentation/modulename}}}}
{{documentation/{{documentation/version}}/module-introduction-row}}
This work is part of the National Alliance for Medical Image Computing (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NA-MIC can be obtained from the [http://www.na-mic.org/ NA-MIC website]. 
Author: Matthew Woehlke, Kitware 
Contact: Matthew Woehlke, <email>matthew.woehlke@kitware.com</email> 
{{documentation/{{documentation/version}}/module-introduction-row}}
{{documentation/{{documentation/version}}/module-introduction-logo-gallery
|{{collaborator|logo|kitware}}|{{collaborator|longname|kitware}}
|{{collaborator|logo|namic}}|{{collaborator|longname|namic}}
}}
{{documentation/{{documentation/version}}/module-introduction-end}}


{{documentation/{{documentation/version}}/module-section|Module Description}}
The Extension Wizard modules provides a graphical interface within Slicer to aid in the creation of Slicer extensions.


{{documentation/{{documentation/version}}/module-section|Use Cases}}
N/A


{{documentation/{{documentation/version}}/module-section|Tutorials}}
N/A


{{documentation/{{documentation/version}}/module-section|Panels and their use}}
== Extension Tools ==

* Create Extension: Create a new extension from a specified template, given a name and destination.
* Select Extension: Choose an existing extension to edit.

When creating a template, the newly created template is automatically selected for editing. When selecting an extension, if the extension provides scripted modules that are not already loaded, an option to load such modules is provided.

== Extension Editor ==

* Name: The name of the currently selected extension.
* Location: The location (on disk) of the currently selected extension.
* Repository: If available, the upstream URL of the repository hosting the extension.
* Contents: A tree view showing the file contents of the currently selected extension.
* Add Module to Extension: Create a new module from a specified template, given a name, and add it to the selected extension.
* Edit Extension Metadata: Edit metadata associated with the extension (such as the name, contributors, etc.).

== Settings ==

The Extension Wizard module provides a settings page, which is accessible via Slicer's Application Settings.

* Built-in template path: If found, displays the location of the built-in templates.
* Additional template paths: A list of additional locations containing categorized templates.
* Additional template paths for ''<category>'': A list of additional locations containing templates for a particular category (e.g. extensions, modules).

A "template" is a directory containing a collection of files which comprise that template. Additional paths should point to directories which ''contain'' such template directories, ''not'' the directory of the template itself. A categorized template directory should have directories for one or more categories, which in turn contain templates.

The built-in templates provide an example of the correct layout for a categorized template directory. (Each category directory is in turn an example of a template collection for that category.)


{{documentation/{{documentation/version}}/module-section|Similar Modules}}
N/A


{{documentation/{{documentation/version}}/module-section|References}}
N/A


{{documentation/{{documentation/version}}/module-section|Information for Developers}}
{{documentation/{{documentation/version}}/module-developerinfo}}
The Extension Wizard module makes extensive use of the SlicerWizard Python package, which is also used by the CLI [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]].

{{documentation/{{documentation/version}}/module-footer}}

Documentation/Nightly/Modules

2014-06-04T19:41:08Z

Matthew.woehlke: /* Developer Tools */

<noinclude>{{documentation/versioncheck}}</noinclude>
=Modules by Category=
==Core Modules==

{{documentation/{{documentation/version}}/Developers/random-image}}

*[[Documentation/{{documentation/version}}/Modules/Annotations|Annotations]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/Colors|Colors]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/Data|Data]] (Julien Finet)
*[[Documentation/{{documentation/version}}/Modules/DICOM|DICOM]] (Steve Pieper)
*[[Documentation/{{documentation/version}}/Modules/Editor|Editor]] (Steve Pieper)
**[[Documentation/{{documentation/version}}/Modules/Editor/WatershedFromMarkers|WatershedFromMarkers]] (Bradley Lowekamp) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/Markups|Markups]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/Models|Models]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/SceneViews|SceneViews]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/Transforms|Transforms]] (Alex Yarmarkovich)
*[[Documentation/{{documentation/version}}/Modules/ViewControllers|View Controllers]] (Jim Miller)
*[[Documentation/{{documentation/version}}/Modules/Volumes|Volumes]] (Steve Pieper)
*[[Documentation/{{documentation/version}}/Modules/VolumeRendering|Volume Rendering]] (Julien Finet)
*[[Documentation/{{documentation/version}}/Modules/SlicerWelcome|Welcome to Slicer]] (Wendy Plesniak)

==Wizards==

==Informatics==
*[[Documentation/{{documentation/version}}/Modules/DataStore|Data Store]] (Charles Marion)
*[[Documentation/{{documentation/version}}/Modules/SampleData|Sample Data]] (Steve Pieper)

==Registration==
*[[:Category:Documentation/{{documentation/version}}/Modules/Registration|Introduction to Registration]] (Dominik Meier)
*[[Documentation/{{documentation/version}}/Modules/BRAINSFit|General Brainsfit Registration]] (Hans Johnson)
*[[Documentation/{{documentation/version}}/Modules/BRAINSResample|Resample Image (BRAINS)]] (Hans Johnson)
*Specialized
**[[Documentation/{{documentation/version}}/Modules/ACPCTransform|ACPC Transform]] (Nicole Aucoin)
**[[Documentation/{{documentation/version}}/Modules/BRAINSDemonWarp|Demon Registration (BRAINS)]] (Hans Johnson)
**[[Documentation/{{documentation/version}}/Modules/FiducialRegistration|Fiducial Registration]] (Stephen Aylward) {{wip}}
**Vector Demon Registration (Hans Johnson)
**[[Documentation/{{documentation/version}}/Modules/Reformat|Reformat]] (Michael Jeulin-Lagarrigue)
**[[Documentation/{{documentation/version}}/Modules/SegmentationAidedRegistration|Segmentation Aided Registration]] (Yi Gao) {{wip}}

==Segmentation==
*[[Documentation/{{documentation/version}}/Modules/EMSegment Easy|EMSegment Easy (no atlas)]] (Kilian Pohl)
*[[Documentation/{{documentation/version}}/Modules/EMSegmenter|EMSegment (with atlas)]] (Kilian Pohl)
*[[Documentation/{{documentation/version}}/Modules/SimpleRegionGrowingSegmentation|Simple Region Growing Segmentation]] (Jim Miller, Harini Veeraraghavan)
*[[Documentation/{{documentation/version}}/Modules/Editor|Editor]] (Steve Pieper)
*Specialized
**[[Documentation/{{documentation/version}}/Modules/EMSegment Command-line | EMSegment Command-line]] (Kilian Pohl)
**[[Documentation/{{documentation/version}}/Modules/ForegroundMasking|Foreground Masking (BRAINS)]] (Hans Johnson)
**[[Documentation/{{documentation/version}}/Modules/RobustStatisticsSegmenter|Robust Statistics Segmenter]] (Yi Gao)
**[[Documentation/{{documentation/version}}/Modules/LAScarSegmenter|Left Atrial Scar Segmenter]] (Liangjia Zhu)
**[[Documentation/{{documentation/version}}/Modules/LASegmenter|Left Atrium Segmenter]] (Liangjia Zhu)
**[[Documentation/{{documentation/version}}/Modules/FastGrowCut|Fast GrowCut]] (Liangjia Zhu) {{wip}}

==Quantification==
*[[Documentation/{{documentation/version}}/Modules/DataProbe|Data Probe]] (Steve Pieper)
*[[Documentation/{{documentation/version}}/Modules/LabelStatistics|Label Statistics]] (Steve Pieper)
*[[Documentation/{{documentation/version}}/Modules/PETStandardUptakeValueComputation|PET Standard Uptake Value Computation]] (Nicole Aucoin)

==Diffusion==
*DWI to Full Brain Tractography (Demian Wasserman) {{wip}}
*Denoising
**[[Documentation/{{documentation/version}}/Modules/DWIJointRicianLMMSEFilter|DWI Joint Rician LMMSE Image Filter]] (Demian Wasserman) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/DWIRicianLMMSEFilter|DWI Rician LMMSE Filter]] (Demian Wasserman) {{wip}}
*Tractography
**[[Documentation/{{documentation/version}}/Modules/TractographyDisplay|Tractography Display]] (Demian Wasserman) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/TractographyFiducialSeeding|Tractography Interactive Seeding]] (Alex Yarmarkovich)
**[[Documentation/{{documentation/version}}/Modules/TractographyLabelMapSeeding|Tractography Label Map Seeding]] (Demian Wasserman) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/UKFTractography|UKF Tractography]]
*Utilities
**[[Documentation/{{documentation/version}}/Modules/DWIToDTIEstimation|DWI To DTI Estimation]] (Demian Wasserman) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/DiffusionTensorScalarMeasurements|Diffusion Tensor Scalar Measurements]] (Demian Wasserman)
**[[Documentation/{{documentation/version}}/Modules/DiffusionWeightedVolumeMasking|Diffusion Weighted Volume Masking]] (Demian Wasserman) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/ResampleDTIVolume|Resample DTI Volume]] (Demian Wasserman) {{wip}}
*Data Conversion
**[[Documentation/{{documentation/version}}/Modules/DTIImport|DTIImport]] {{wip}} (Sonia Pujol)
**[[Documentation/{{documentation/version}}/Modules/DTIExport|DTIExport]] {{wip}} (Sonia Pujol)
**[[Documentation/{{documentation/version}}/Modules/FiberBundleToLabelMap|Fiber Bundle to Label Map]] (Steve Pieper)

==IGT==
*[[Documentation/{{documentation/version}}/Modules/OpenIGTLinkIF| OpenIGTLink IF]] (Junichi Tokuda) {{wip}}
*[[Documentation/{{documentation/version}}/Extensions/SlicerIGT| SlicerIGT]] (Tamas Ungi, Junichi Tokuda) {{wip}}

==Filtering==
*[[Documentation/{{documentation/version}}/Modules/N4ITKBiasFieldCorrection | N4ITK Bias Field Correction]] (Andrey Fedorov)
*[[Documentation/{{documentation/version}}/Modules/CheckerBoardFilter|CheckerBoard Filter]] (Jim Miller) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/ExtractSkeleton|Extract Skeleton]] (Jim Miller) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/HistogramMatching|Histogram Matching]] (Jim Miller) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/ImageLabelCombine|Image Label Combine]] (Alex Yarmarkovich)
*[[Documentation/{{documentation/version}}/Modules/ResampleScalarVectorDWIVolume|Resample Scalar/Vector/DWI Volume]] (Francois Budin) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/ThresholdScalarVolume|Threshold Scalar Volume]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/VotingBinaryHoleFillingImageFilter|Voting Binary Hole Filling Image Filter]] (Jim Miller) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/SimpleFilters|Simple Filters]] (Bradley Lowekamp) {{wip}}
*Arithmetic
**[[Documentation/{{documentation/version}}/Modules/AddScalarVolumes|Add Scalar Volumes]] (Jim Miller) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/CastScalarVolume| Cast Scalar Volume]] (Nicole Aucoin)
**[[Documentation/{{documentation/version}}/Modules/MaskScalarVolume| Mask Scalar Volume]] (Nicole Aucoin)
**[[Documentation/{{documentation/version}}/Modules/MultiplyScalarVolumes| Multiply Scalar Volumes]] (Jim Miller) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/SubtractScalarVolumes| Subtract Scalar Volumes]] (Jim Miller) {{wip}}
*Denoising
**[[Documentation/{{documentation/version}}/Modules/GradientAnisotropicDiffusion |Gradient Anisotropic Diffusion]] (Jim Miller) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/CurvatureAnisotropicDiffusion|Curvature Anisotropic Diffusion]] (Jim Miller) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/GaussianBlurImageFilter|Gaussian Blur Image Filter]] (Stephen Aylward) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/MedianImageFilter|Median Image Filter]] (Jim Miller) {{wip}}
*Morphology
**[[Documentation/{{documentation/version}}/Modules/GrayscaleFillHoleImageFilter|Grayscale Fill Hole Image Filter]] (Jim Miller)
**[[Documentation/{{documentation/version}}/Modules/GrayscaleGrindPeakImageFilter|Grayscale Grind Peak Image Filter]] (Jim Miller) {{wip}}

==Surface Models==
*[[Documentation/{{documentation/version}}/Modules/GrayscaleModelMaker| Grayscale Model Maker]] (Jim Miller) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/LabelMapSmoothing|Label Map Smoothing]] {{wip}}
*[[Documentation/{{documentation/version}}/Modules/MergeModels| Merge Models]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/ModelMaker| Model Maker]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/ModelToLabelMap| Model To LabelMap]] (Nicole Aucoin)
*[[Documentation/{{documentation/version}}/Modules/ProbeVolumeWithModel| Probe Volume With Model]] (Lauren O'Donnell) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/SurfaceToolbox| SurfaceToolbox]] (Luca Antiga)

==Converters==
*[[Documentation/{{documentation/version}}/Modules/CreateDICOMSeries|Create DICOM Series]] (Jim Miller) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/Crop Volume|Crop Volume]] (Andrey Fedorov)
*[[Documentation/{{documentation/version}}/Modules/DicomToNrrdConverter|Dicom to Nrrd Converter]] (Jim Miller)
*[[Documentation/{{documentation/version}}/Modules/OrientScalarVolume| Orient Scalar Volume]] (Jim Miller)
*[[Documentation/{{documentation/version}}/Modules/VectorToScalarVolume| Vector to Scalar Volume]] (Steve Pieper)
{{wip}}

==Endoscopy==
*[[Documentation/{{documentation/version}}/Modules/Endoscopy|Endoscopy]] (Steve Pieper)

=={{wip}} Work in Progress {{wip}}==
* MultiVolume Support
**[[Documentation/{{documentation/version}}/Modules/MultiVolumeImporter|MultiVolume Importer]] (Andrey Fedorov)
**[[Documentation/{{documentation/version}}/Modules/MultiVolumeExplorer|MultiVolume Explorer]] (Andrey Fedorov)

==Developer Tools==
*[[Documentation/{{documentation/version}}/Modules/Cameras|Cameras]] (Julien Finet) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/EventBroker|Event Broker]] (Julien Finet) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/ExecutionModelTour |Execution Model Tour]] (JC Fillion-Robin) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/ExtensionWizard |Extension Wizard]] (Matthew Woehlke) {{wip}}
*[[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|Module Template]] (JC Fillion-Robin)
*Performance Tests
*Tractography

==Legacy==
*Converters
**[[Documentation/{{documentation/version}}/Modules/BSplineToDeformationField|BSpline To Deformation Field]]
*Diffusion
**Denoising
***[[Documentation/{{documentation/version}}/Modules/DWIUnbiasedNonLocalMeansFilter|DWI Unbiased Non Local Means Filter]]
*Filtering
**[[Documentation/{{documentation/version}}/Modules/MRIBiasFieldCorrection|MRI Bias Field Correction]] (Sylvain Jaume) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/OtsuThresholdImageFilter|Otsu Threshold Image Filter]] (Bill Lorensen) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/ResampleScalarVolume|Resample Scalar Volume]] (Jim Miller) {{wip}}
*Registration
**[[Documentation/{{documentation/version}}/Modules/RigidRegistration|Rigid Registration]] (Jim Miller) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/AffineRegistration|Affine Registration]] (Daniel Blezek) {{wip}}
**[[Documentation/{{documentation/version}}/Modules/BSplineDeformableRegistration|BSpline Deformable Registration]] {{wip}}
**[[Documentation/{{documentation/version}}/Modules/ExpertAutomatedRegistration|Expert Automated Registration]] {{wip}}
**[[Documentation/{{documentation/version}}/Modules/LinearRegistration|Linear Registration]] {{wip}}
**[[Documentation/{{documentation/version}}/Modules/MultiResolutionAffineRegistration|MultiResolution Affine Registration]] (Casey Goodlett){{wip}}

*Segmentation
**[[Documentation/{{documentation/version}}/Modules/OtsuThresholdSegmentation|Otsu Threshold Segmentation]] (Bill Lorensen) {{wip}}

Documentation/Nightly/Developers/ExtensionWizard

2014-06-02T22:25:21Z

Matthew.woehlke: /* Invoking the Wizard */

== 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 ===

[[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 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 [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows).

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)
** [http://github.com/gitpython-developers/GitPython/ GitPython]
** [http://jacquev6.github.io/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 ====

Git is available via [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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).

=== 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 '<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 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
<nowiki/>
# 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
<nowiki/>
# 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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[Documentation/{{documentation/version}}/Developers/Modules|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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
slicerExtensionWizard --templatePath ~/code/Templates
<nowiki/>
# 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:

# 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
<nowiki/>
# 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 [[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:

# "Publish" your extension by making it available on a publicly accessible repository.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''

{{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:

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.

{{notice|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
<nowiki/>
# 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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-06-02T22:24:41Z

Matthew.woehlke: /* Requirements */ remove redundant notice

== 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 ===

[[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 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 [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows).

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)
** [http://github.com/gitpython-developers/GitPython/ GitPython]
** [http://jacquev6.github.io/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 ====

Git is available via [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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).

=== 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 '<code>/path/to</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 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
<nowiki/>
# 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
<nowiki/>
# 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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[Documentation/{{documentation/version}}/Developers/Modules|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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
slicerExtensionWizard --templatePath ~/code/Templates
<nowiki/>
# 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:

# 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
<nowiki/>
# 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 [[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:

# "Publish" your extension by making it available on a publicly accessible repository.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''

{{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:

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.

{{notice|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
<nowiki/>
# 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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-06-02T22:23:19Z

Matthew.woehlke: update instructions for recently added wizard launcher script

== 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 ===

[[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 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 [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows).

{{notice|On Windows, you will also need [http://www.gnu.org/software/bash/ bash] to use the launcher script. The "git bash" that comes with msys git should suffice.}}

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)
** [http://github.com/gitpython-developers/GitPython/ GitPython]
** [http://jacquev6.github.io/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 ====

Git is available via [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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).

=== 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 '<code>/path/to</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 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
<nowiki/>
# 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
<nowiki/>
# 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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[Documentation/{{documentation/version}}/Developers/Modules|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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
slicerExtensionWizard --templatePath ~/code/Templates
<nowiki/>
# 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:

# 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
<nowiki/>
# 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 [[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:

# "Publish" your extension by making it available on a publicly accessible repository.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''

{{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:

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.

{{notice|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
<nowiki/>
# 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.

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

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.

Documentation/Labs/ExtensionsFrameworkRoadmap

2014-05-21T20:46:48Z

Matthew.woehlke: /* Progress */

This page serves as roadmap for the Slicer Extensions framework.

= Extension contribution process =

The goal here is to simplify the number of steps allowing people to contribute extension.

More specifically, we would like to make it very easy for people to create a python extension by:
* removing the need for a Slicer build tree
* reducing the number of steps required to create and load an extension from a template
* simplifying how an extension is contributed to the index
* simplifying how an extension can be uploaded to the extension server

== Current process ==

The current process to create an empty extension is documented [[Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions|here]], then the steps to contribute the extension are documented [[Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File|here]].

For all type of extension (C++ or python), the steps can then be summarized as:

=== To create an extension ===
# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''5 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

=== To save extension code ===
# Github: Create an account
# Github: Create a repository
# Workstation -> Github: Push local work on Github

=== To contribute an extension to Index ===
# SlicerWiki: Create documentation page
# Extension Server: Create an account
# Extension Server: Join community
# Extension Server: Ask permission for experimental folder.
# Workstation: Configure upload credential
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Github: Fork ExtensionsIndex
# Workstation: Clone fork locally
# Workstation: Create branch add-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Push the topic to fork
# Github: Click on Pull request button

=== To update an extension in Index ===
# SlicerWiki: Update documentation page
# Workstation: In extension index clone: '''5 commands to type'''
# Workstation: Create branch update-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Create pull request manually creating the URL
# Github: Add a comment in the pull request with a Compare link also manually generated

== Proposed changes ==

=== To create an extension ===

For all type of extensions, the simplified workflow is:

# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''1 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

For scripted extensions, creation directly from within Slicer:

# Slicer: Modules -> Developer -> ExtensionWizard
# ExtensionWizard module: Set name, description, contributors etc ... then click on Create
## Set the working directory ? Where to create.
## External link to the github account creation page (will open web browswer or tab in the extension manager ?)
## Optionally create github repo and pre-populate repo ...
# Path to the module(s) in extension should be added to the additional module path.
# Slicer: Restart - 'Foo' module should show up. ''Note: This last step could probably be removed''

=== To save extension code ===

For all type of extensions, the simplified workflow is:

# Github: Create an account
# Workstation -> Github: Create repository done with '''1 command'''. <code>ExtensionWizard.py --publish ~/code/MyExtension</code>

For scripted extensions:

# initial publish on github done from the ExtensionWizard module. See above

=== To publish extension code update===

For all type of extensions, the workflow is:

# git commit, ..., git push

=== To contribute an extension to the Index ===
# SlicerWiki: Create documentation page.
## Need to check with BHW if wiki version can be updated so that any IP could use the mediawiki API
# Extension Server: Create an account [Join community + experimental folder permission consolidated in one location]
## Create a "Slicer Extensions" community where user have to request access
## Folks belonging to the "Slicer Extensions" would be automatically be granted access
## Jc: Check with Midas team with user can request access to community
# Workstation: Configure upload credential
## Update [[Documentation/Nightly/Developers/Tutorials/ObtainExtensionServerApiKey|documentation]] to explain that MIDAS_API_* variable can be set in the env.
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Add extension to the index using '''1 command''': <code>ExtensionWizard.py --contribute --target master ~/code/MyExtension</code>

== Progress ==

* Improve Wizard to create empty extension: reduce number of terminal commands to 1
** [http://na-mic.org/Mantis/view.php?id=3566 3566: Wizard: Simplify creation of extensions/modules]: {{done}} Completed - Review in progress
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add ExtensionWizard wiki page]: {{done}} Completed - Review in progress -See [[Documentation/Nightly/Developers/ExtensionWizard]]
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add developer documentation for ExtensionWizard]: {{done}} Completed - Review in progress - See [http://mwoehlke-kitware.github.io/Slicer/SlicerWizard/]
* Publish extension on Github by creating github repo - {{done}} Completed - Review in progress

* In case of Python extension, remove the need for a Slicer build tree: '''50%'''
** Wizard: Remove dependency on build tree or CMake generated file. {{done}} - Review in progress
** Add install rules for the template source code - To make them available from an installed Slicer
** [http://na-mic.org/Mantis/view.php?id=3269 3269: Simplify contribution of scripted extension]: '''50%'''
** [http://na-mic.org/Mantis/view.php?id=3603 3603 Slicer: Creation of python extension directly from Slicer.] {{review}} '''Awaiting Review'''
*** Slicer: Optional Restart. '''ToBeDone''' (do we actually need this?)

* [http://na-mic.org/Mantis/view.php?id=3604 3604 ExtensionServer: Consolidate ExtensionsIndex account creation.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3605 3605 SlicerWiki: Automatic creation of extension wiki page.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3606 3606 Slicer: Given an extension python script. Should be possible to upload the extension directly from Slicer.] '''ToBeDone'''

= Extensions Catalog / Manager =

The goal here is to improve the overall user experience associated with the extension catalog.

When accessed from within Slicer the catalog is also referred as extensions manager.

== Progress ==

* <s>[http://na-mic.org/Mantis/view.php?id=3564 3564: Add search option in extension manager].</s> {{done}} '''Completed'''
* <s>[http://na-mic.org/Mantis/view.php?id=3602 3602: ExensionsManager - Add a "Show url" link'].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2089 2089: Either on-demand or when slicer starts, check if there are available extensions update.]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=3607 3607: ExtensionManager: Exclude category "Example" from "All" listing ].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2779 2779: Mechanism to keep track of the installed extensions across version]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=2912 2912: Install dependent extensions ].</s> {{done}} '''Completed'''

* Low priority:
** [http://na-mic.org/Mantis/view.php?id=2334 2334: Differentiate different type of extenions in extension manager: Concept of channel]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=2778 2778: Add "Download stats" on each extension page ]. '''ToBeDone'''
** <s>[http://na-mic.org/Mantis/view.php?id=3608 3608: ExtensionsManager: Display description for installed extensions.].</s> {{done}} '''Completed'''
** Consolidate rating across extension version. See [https://github.com/midasplatform/slicerappstore/issues/9#issuecomment-15643678 midasplatform/slicerappstore/issues/9]

= Extension developer documentation =

The goal is to consolidate the existing documentation so that it is easy to understand what is the python API available to the Slicer python extension developer.

== Progress ==

* Generate Slicer python API documentation. '''In progress'''. See experiment http://mwoehlke-kitware.github.io/Slicer/Base/

= Extensions Wizard UI =

The wizard UI will provide a Slicer module allowing to:
* easily create / publish / contribute extensions directly from Slicer.
* directly load scripted modules after they are created.

[[File:Slicer-in-app-wizard1.png|250px]]

== Progress ==

See issues [http://na-mic.org/Mantis/view.php?id=3603 #3603], [http://na-mic.org/Mantis/view.php?id=3606 #3606] listed above.

Documentation/Labs/ExtensionsFrameworkRoadmap

2014-05-05T21:15:03Z

Matthew.woehlke:

This page serves as roadmap for the Slicer Extensions framework.

= Extension contribution process =

The goal here is to simplify the number of steps allowing people to contribute extension.

More specifically, we would like to make it very easy for people to create a python extension by:
* removing the need for a Slicer build tree
* reducing the number of steps required to create and load an extension from a template
* simplifying how an extension is contributed to the index
* simplifying how an extension can be uploaded to the extension server

== Current process ==

The current process to create an empty extension is documented [[Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions|here]], then the steps to contribute the extension are documented [[Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File|here]].

For all type of extension (C++ or python), the steps can then be summarized as:

=== To create an extension ===
# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''5 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

=== To save extension code ===
# Github: Create an account
# Github: Create a repository
# Workstation -> Github: Push local work on Github

=== To contribute an extension to Index ===
# SlicerWiki: Create documentation page
# Extension Server: Create an account
# Extension Server: Join community
# Extension Server: Ask permission for experimental folder.
# Workstation: Configure upload credential
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Github: Fork ExtensionsIndex
# Workstation: Clone fork locally
# Workstation: Create branch add-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Push the topic to fork
# Github: Click on Pull request button

=== To update an extension in Index ===
# SlicerWiki: Update documentation page
# Workstation: In extension index clone: '''5 commands to type'''
# Workstation: Create branch update-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Create pull request manually creating the URL
# Github: Add a comment in the pull request with a Compare link also manually generated

== Proposed changes ==

=== To create an extension ===

For all type of extensions, the simplified workflow is:

# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''1 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

For scripted extensions, creation directly from within Slicer:

# Slicer: Modules -> Developer -> ExtensionWizard
# ExtensionWizard module: Set name, description, contributors etc ... then click on Create
## Set the working directory ? Where to create.
## External link to the github account creation page (will open web browswer or tab in the extension manager ?)
## Optionally create github repo and pre-populate repo ...
# Path to the module(s) in extension should be added to the additional module path.
# Slicer: Restart - 'Foo' module should show up. ''Note: This last step could probably be removed''

=== To save extension code ===

For all type of extensions, the simplified workflow is:

# Github: Create an account
# Workstation -> Github: Create repository done with '''1 command'''. <code>ExtensionWizard.py --publish ~/code/MyExtension</code>

For scripted extensions:

# initial publish on github done from the ExtensionWizard module. See above

=== To publish extension code update===

For all type of extensions, the workflow is:

# git commit, ..., git push

=== To contribute an extension to the Index ===
# SlicerWiki: Create documentation page.
## Need to check with BHW if wiki version can be updated so that any IP could use the mediawiki API
# Extension Server: Create an account [Join community + experimental folder permission consolidated in one location]
## Create a "Slicer Extensions" community where user have to request access
## Folks belonging to the "Slicer Extensions" would be automatically be granted access
## Jc: Check with Midas team with user can request access to community
# Workstation: Configure upload credential
## Update [[Documentation/Nightly/Developers/Tutorials/ObtainExtensionServerApiKey|documentation]] to explain that MIDAS_API_* variable can be set in the env.
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Add extension to the index using '''1 command''': <code>ExtensionWizard.py --contribute --target master ~/code/MyExtension</code>

== Progress ==

* Improve Wizard to create empty extension: reduce number of terminal commands to 1
** [http://na-mic.org/Mantis/view.php?id=3566 3566: Wizard: Simplify creation of extensions/modules]: {{done}} Completed - Review in progress
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add ExtensionWizard wiki page]: {{done}} Completed - Review in progress -See [[Documentation/Nightly/Developers/ExtensionWizard]]
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add developer documentation for ExtensionWizard]: {{done}} Completed - Review in progress - See [http://mwoehlke-kitware.github.io/Slicer/SlicerWizard/]
* Publish extension on Github by creating github repo - {{done}} Completed - Review in progress

* In case of Python extension, remove the need for a Slicer build tree: '''50%'''
** Wizard: Remove dependency on build tree or CMake generated file. {{done}} - Review in progress
** Add install rules for the template source code - To make them available from an installed Slicer
** [http://na-mic.org/Mantis/view.php?id=3269 3269: Simplify contribution of scripted extension]: '''50%'''
** [http://na-mic.org/Mantis/view.php?id=3603 3603 Slicer: Creation of python extension directly from Slicer.] {{review}} '''Awaiting Review'''
*** Slicer: Optional Restart. '''ToBeDone''' (do we actually need this?)

* [http://na-mic.org/Mantis/view.php?id=3604 3604 ExtensionServer: Consolidate ExtensionsIndex account creation.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3605 3605 SlicerWiki: Automatic creation of extension wiki page.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3606 3606 Slicer: Given an extension python script. Should be possible to upload the extension directly from Slicer.] '''ToBeDone'''

= Extensions Catalog / Manager =

The goal here is to improve the overall user experience associated with the extension catalog.

When accessed from within Slicer the catalog is also referred as extensions manager.

== Progress ==

* <s>[http://na-mic.org/Mantis/view.php?id=3564 3564: Add search option in extension manager].</s> {{done}} '''Completed'''
* <s>[http://na-mic.org/Mantis/view.php?id=3602 3602: ExensionsManager - Add a "Show url" link'].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2089 2089: Either on-demand or when slicer starts, check if there are available extensions update.]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=3607 3607: ExtensionManager: Exclude category "Example" from "All" listing ].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2779 2779: Mechanism to keep track of the installed extensions across version]. '''ToBeDone'''
* [http://na-mic.org/Mantis/view.php?id=2912 2912: Install dependent extensions ]. '''ToBeDone'''

* Low priority:
** [http://na-mic.org/Mantis/view.php?id=2334 2334: Differentiate different type of extenions in extension manager: Concept of channel]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=2778 2778: Add "Download stats" on each extension page ]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=3608 3608: ExtensionsManager: Display description for installed extensions.]. {{review}} '''Awaiting Review'''
** Consolidate rating across extension version. See [https://github.com/midasplatform/slicerappstore/issues/9#issuecomment-15643678 midasplatform/slicerappstore/issues/9]

= Extension developer documentation =

The goal is to consolidate the existing documentation so that it is easy to understand what is the python API available to the Slicer python extension developer.

== Progress ==

* Generate Slicer python API documentation. '''In progress'''. See experiment http://mwoehlke-kitware.github.io/Slicer/Base/

= Extensions Wizard UI =

The wizard UI will provide a Slicer module allowing to:
* easily create / publish / contribute extensions directly from Slicer.
* directly load scripted modules after they are created.

[[File:Slicer-in-app-wizard1.png|250px]]

== Progress ==

See issues [http://na-mic.org/Mantis/view.php?id=3603 #3603], [http://na-mic.org/Mantis/view.php?id=3606 #3606] listed above.

Documentation/Labs/ExtensionsFrameworkRoadmap

2014-04-18T18:17:51Z

Matthew.woehlke: /* Progress */

This page serves as roadmap for the Slicer Extensions framework.

= Extension contribution process =

The goal here is to simplify the number of steps allowing people to contribute extension.

More specifically, we would like to make it very easy for people to create a python extension by:
* removing the need for a Slicer build tree
* reducing the number of steps required to create and load an extension from a template
* simplifying how an extension is contributed to the index
* simplifying how an extension can be uploaded to the extension server

== Current process ==

The current process to create an empty extension is documented [[Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions|here]], then the steps to contribute the extension are documented [[Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File|here]].

For all type of extension (C++ or python), the steps can then be summarized as:

=== To create an extension ===
# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''5 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

=== To save extension code ===
# Github: Create an account
# Github: Create a repository
# Workstation -> Github: Push local work on Github

=== To contribute an extension to Index ===
# SlicerWiki: Create documentation page
# Extension Server: Create an account
# Extension Server: Join community
# Extension Server: Ask permission for experimental folder.
# Workstation: Configure upload credential
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Github: Fork ExtensionsIndex
# Workstation: Clone fork locally
# Workstation: Create branch add-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Push the topic to fork
# Github: Click on Pull request button

=== To update an extension in Index ===
# SlicerWiki: Update documentation page
# Workstation: In extension index clone: '''5 commands to type'''
# Workstation: Create branch update-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Create pull request manually creating the URL
# Github: Add a comment in the pull request with a Compare link also manually generated

== Proposed changes ==

=== To create an extension ===

For all type of extensions, the simplified workflow is:

# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''1 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

For scripted extensions, creation directly from within Slicer:

# Slicer: Modules -> Developer -> ExtensionWizard
# ExtensionWizard module: Set name, description, contributors etc ... then click on Create
## Set the working directory ? Where to create.
## External link to the github account creation page (will open web browswer or tab in the extension manager ?)
## Optionally create github repo and pre-populate repo ...
# Path to the module(s) in extension should be added to the additional module path.
# Slicer: Restart - 'Foo' module should show up. ''Note: This last step could probably be removed''

=== To save extension code ===

For all type of extensions, the simplified workflow is:

# Github: Create an account
# Workstation -> Github: Create repository done with '''1 command'''. <code>ExtensionWizard.py --publish ~/code/MyExtension</code>

For scripted extensions:

# initial publish on github done from the ExtensionWizard module. See above

=== To publish extension code update===

For all type of extensions, the workflow is:

# git commit, ..., git push

=== To contribute an extension to the Index ===
# SlicerWiki: Create documentation page.
## Need to check with BHW if wiki version can be updated so that any IP could use the mediawiki API
# Extension Server: Create an account [Join community + experimental folder permission consolidated in one location]
## Create a "Slicer Extensions" community where user have to request access
## Folks belonging to the "Slicer Extensions" would be automatically be granted access
## Jc: Check with Midas team with user can request access to community
# Workstation: Configure upload credential
## Update [[Documentation/Nightly/Developers/Tutorials/ObtainExtensionServerApiKey|documentation]] to explain that MIDAS_API_* variable can be set in the env.
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Add extension to the index using '''1 command''': <code>ExtensionWizard.py --contribute --target master ~/code/MyExtension</code>

== Progress ==

* Improve Wizard to create empty extension: reduce number of terminal commands to 1
** [http://na-mic.org/Mantis/view.php?id=3566 3566: Wizard: Simplify creation of extensions/modules]: {{done}} Completed - Review in progress
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add ExtensionWizard wiki page]: {{done}} Completed - Review in progress -See [[Documentation/Nightly/Developers/ExtensionWizard]]
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add developer documentation for ExtensionWizard]: {{done}} Completed - Review in progress - See [http://mwoehlke-kitware.github.io/Slicer/SlicerWizard/]
* Publish extension on Github by creating github repo - {{done}} Completed - Review in progress

* In case of Python extension, remove the need for a Slicer build tree: '''50%'''
** Wizard: Remove dependency on build tree or CMake generated file. {{done}} - Review in progress
** Add install rules for the template source code - To make them available from an installed Slicer
** [http://na-mic.org/Mantis/view.php?id=3269 3269: Simplify contribution of scripted extension]: '''50%'''
** [http://na-mic.org/Mantis/view.php?id=3603 3603 Slicer: Creation of python extension directly from Slicer.] {{review}} '''Awaiting Review'''
*** Slicer: Optional Restart. '''ToBeDone''' (do we actually need this?)

* [http://na-mic.org/Mantis/view.php?id=3604 3604 ExtensionServer: Consolidate ExtensionsIndex account creation.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3605 3605 SlicerWiki: Automatic creation of extension wiki page.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3606 3606 Slicer: Given an extension python script. Should be possible to upload the extension directly from Slicer.] '''ToBeDone'''

= Extensions Catalog / Manager =

The goal here is to improve the overall user experience associated with the extension catalog.

When accessed from within Slicer the catalog is also referred as extensions manager.

== Progress ==

* [http://na-mic.org/Mantis/view.php?id=3564 3564: Add search option in extension manager]. {{review}} '''Awaiting Review'''
* <s>[http://na-mic.org/Mantis/view.php?id=3602 3602: ExensionsManager - Add a "Show url" link'].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2089 2089: Either on-demand or when slicer starts, check if there are available extensions update.]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=3607 3607: ExtensionManager: Exclude category "Example" from "All" listing ].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2779 2779: Mechanism to keep track of the installed extensions across version]. '''ToBeDone'''
* [http://na-mic.org/Mantis/view.php?id=2912 2912: Install dependent extensions ]. '''ToBeDone'''

* Low priority:
** [http://na-mic.org/Mantis/view.php?id=2334 2334: Differentiate different type of extenions in extension manager: Concept of channel]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=2778 2778: Add "Download stats" on each extension page ]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=3608 3608: ExtensionsManager: Display description for installed extensions.]. Code complete, waiting on [http://na-mic.org/Mantis/view.php?id=3564 3564] to be merged
** Consolidate rating across extension version. See [https://github.com/midasplatform/slicerappstore/issues/9#issuecomment-15643678 midasplatform/slicerappstore/issues/9]

= Extension developer documentation =

The goal is to consolidate the existing documentation so that it is easy to understand what is the python API available to the Slicer python extension developer.

== Progress ==

* Generate Slicer python API documentation. '''In progress'''. See experiment http://mwoehlke-kitware.github.io/Slicer/Base/

= Extensions Wizard UI =

The wizard UI will provide a Slicer module allowing to:
* easily create / publish / contribute extensions directly from Slicer.
* directly load scripted modules after they are created.

[[File:Slicer-in-app-wizard1.png|250px]]

== Progress ==

See issues [http://na-mic.org/Mantis/view.php?id=3603 #3603], [http://na-mic.org/Mantis/view.php?id=3606 #3606] listed above.

Documentation/Labs/ExtensionsFrameworkRoadmap

2014-04-15T15:33:02Z

Matthew.woehlke: /* Progress */

This page serves as roadmap for the Slicer Extensions framework.

= Extension contribution process =

The goal here is to simplify the number of steps allowing people to contribute extension.

More specifically, we would like to make it very easy for people to create a python extension by:
* removing the need for a Slicer build tree
* reducing the number of steps required to create and load an extension from a template
* simplifying how an extension is contributed to the index
* simplifying how an extension can be uploaded to the extension server

== Current process ==

The current process to create an empty extension is documented [[Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions|here]], then the steps to contribute the extension are documented [[Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File|here]].

For all type of extension (C++ or python), the steps can then be summarized as:

=== To create an extension ===
# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''5 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

=== To save extension code ===
# Github: Create an account
# Github: Create a repository
# Workstation -> Github: Push local work on Github

=== To contribute an extension to Index ===
# SlicerWiki: Create documentation page
# Extension Server: Create an account
# Extension Server: Join community
# Extension Server: Ask permission for experimental folder.
# Workstation: Configure upload credential
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Github: Fork ExtensionsIndex
# Workstation: Clone fork locally
# Workstation: Create branch add-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Push the topic to fork
# Github: Click on Pull request button

=== To update an extension in Index ===
# SlicerWiki: Update documentation page
# Workstation: In extension index clone: '''5 commands to type'''
# Workstation: Create branch update-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Create pull request manually creating the URL
# Github: Add a comment in the pull request with a Compare link also manually generated

== Proposed changes ==

=== To create an extension ===

For all type of extensions, the simplified workflow is:

# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''1 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

For scripted extensions, creation directly from within Slicer:

# Slicer: Modules -> Developer -> ExtensionWizard
# ExtensionWizard module: Set name, description, contributors etc ... then click on Create
## Set the working directory ? Where to create.
## External link to the github account creation page (will open web browswer or tab in the extension manager ?)
## Optionally create github repo and pre-populate repo ...
# Path to the module(s) in extension should be added to the additional module path.
# Slicer: Restart - 'Foo' module should show up. ''Note: This last step could probably be removed''

=== To save extension code ===

For all type of extensions, the simplified workflow is:

# Github: Create an account
# Workstation -> Github: Create repository done with '''1 command'''. <code>ExtensionWizard.py --publish ~/code/MyExtension</code>

For scripted extensions:

# initial publish on github done from the ExtensionWizard module. See above

=== To publish extension code update===

For all type of extensions, the workflow is:

# git commit, ..., git push

=== To contribute an extension to the Index ===
# SlicerWiki: Create documentation page.
## Need to check with BHW if wiki version can be updated so that any IP could use the mediawiki API
# Extension Server: Create an account [Join community + experimental folder permission consolidated in one location]
## Create a "Slicer Extensions" community where user have to request access
## Folks belonging to the "Slicer Extensions" would be automatically be granted access
## Jc: Check with Midas team with user can request access to community
# Workstation: Configure upload credential
## Update [[Documentation/Nightly/Developers/Tutorials/ObtainExtensionServerApiKey|documentation]] to explain that MIDAS_API_* variable can be set in the env.
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Add extension to the index using '''1 command''': <code>ExtensionWizard.py --contribute --target master ~/code/MyExtension</code>

== Progress ==

* Improve Wizard to create empty extension: reduce number of terminal commands to 1
** [http://na-mic.org/Mantis/view.php?id=3566 3566: Wizard: Simplify creation of extensions/modules]: {{done}} Completed - Review in progress
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add ExtensionWizard wiki page]: {{done}} Completed - Review in progress -See [[Documentation/Nightly/Developers/ExtensionWizard]]
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add developer documentation for ExtensionWizard]: {{done}} Completed - Review in progress - See [http://mwoehlke-kitware.github.io/Slicer/SlicerWizard/]
* Publish extension on Github by creating github repo - {{done}} Completed - Review in progress

* In case of Python extension, remove the need for a Slicer build tree: '''50%'''
** Wizard: Remove dependency on build tree or CMake generated file. {{done}} - Review in progress
** Add install rules for the template source code - To make them available from an installed Slicer
** [http://na-mic.org/Mantis/view.php?id=3269 3269: Simplify contribution of scripted extension]: '''50%'''
** Slicer: Creation of python extension directly from within Slicer. '''ToBeDone'''
*** Slicer: Optional Restart. '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3603 3603 Slicer: Creation of python extension directly from Slicer.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3604 3604 ExtensionServer: Consolidate ExtensionsIndex account creation.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3605 3605 SlicerWiki: Automatic creation of extension wiki page.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3606 3606 Slicer: Given an extension python script. Should be possible to upload the extension directly from Slicer.] '''ToBeDone'''

= Extensions Catalog / Manager =

The goal here is to improve the overall user experience associated with the extension catalog.

When accessed from within Slicer the catalog is also referred as extensions manager.

== Progress ==

* [http://na-mic.org/Mantis/view.php?id=3564 3564: Add search option in extension manager]. {{review}} '''Awaiting Review'''
* <s>[http://na-mic.org/Mantis/view.php?id=3602 3602: ExensionsManager - Add a "Show url" link'].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2089 2089: Either on-demand or when slicer starts, check if there are available extensions update.]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=3607 3607: ExtensionManager: Exclude category "Example" from "All" listing ].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2779 2779: Mechanism to keep track of the installed extensions across version]. '''ToBeDone'''

* Low priority:
** [http://na-mic.org/Mantis/view.php?id=2334 2334: Differentiate different type of extenions in extension manager: Concept of channel]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=2778 2778: Add "Download stats" on each extension page ]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=3608 3608: ExtensionsManager: Display description for installed extensions.]. Code complete, waiting on [http://na-mic.org/Mantis/view.php?id=3564 3564] to be merged
** Consolidate rating across extension version. See [https://github.com/midasplatform/slicerappstore/issues/9#issuecomment-15643678 midasplatform/slicerappstore/issues/9]

= Extension developer documentation =

The goal is to consolidate the existing documentation so that it is easy to understand what is the python API available to the Slicer python extension developer.

== Progress ==

* Generate Slicer python API documentation. '''In progress'''. See experiment http://mwoehlke-kitware.github.io/Slicer/Base/

Documentation/Labs/FHSCompliantDirectoryStructure

2014-04-10T20:52:24Z

Matthew.woehlke:

The current install tree structure as documented on [[Documentation/Nightly/Developers]] is not fully compliant with the [https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard Filesystem Hierarchy Standard]. This page aims at documentation how the structure could be updated.

== Rationale ==

For reasons that hopefully do not require enumeration, it is desirable for Slicer to install in a reasonable manner to a system standard prefix, e.g. <tt>/usr/local</tt> or even <tt>/usr</tt>. Ultimately, it would be very cool if distributions were able to package slicer, for which reasonable FHS compliance is a requirement.

== Proposal ==

(Originally by Matthew Woehlke - April 10, 2014)

* move <tt>/Slicer</tt>[[#fn1|[1]]] to <tt>/bin/</tt>
* move <tt>/bin/Python</tt>[[#fn2|[2]]] to one[[#fn3|[3]]] of:
** <tt>/lib/python-${PyVer}/site-packages</tt>
** <tt>/lib/python-${PyVer}/site-packages/slicer${VerMajor}</tt>
** <tt>/share/Slicer-${Ver}/</tt>
*** ...and move <tt>/bin/Python/SlicerWizard</tt> to <tt>/lib/python-${PyVer}/site-packages</tt>
* move <tt>/lib/Python/*</tt>[[#fn4|[4]]] to <tt>/</tt>
* move <tt>/lib/TclTk/*</tt>[[#fn4|[4]]] to <tt>/</tt>
* move <tt>/lib/QtPlugins</tt>[[#fn5|[5]]] to <tt>/lib/Slicer-${Ver}/</tt>
* move <tt>/lib/Slicer*/<third party libs></tt>[[#fn4|[4]]] to <tt>/lib/</tt>
* move <tt>/bin/Slicer{LauncherSettings.ini,SplashScreen.png}</tt>[[#fn6|[6]]] to <tt>/share/Slicer-${Ver}/</tt>

(As a side note, honoring LIB_SUFFIX also would be nice. This is common idiom in e.g. [http://www.fedoraproject.org Fedora] packaging to install libraries to <tt>lib64</tt> rather than <tt>lib</tt>, when building for architectures where that is appropriate.)

=== Footnotes ===

# The FHS (e.g. 3.1) strongly discourages adding entries to <tt>/</tt> or <tt>/usr</tt>. Anyway, this clearly should be in <tt>/bin</tt> so that it is in a reasonable <tt>PATH</tt>. On UNIX systems where <tt>PREFIX=/opt/<product></tt> (or perhaps as a CMake option), it might be okay to install a symlink in <tt>${PREFIX}</tt>. On Windows, a shortcut could be used similarly.
# 3.4.2 forbids subdirectories in <tt>/bin</tt>. While not stated explicitly for <tt>/usr/bin</tt>, many systems now symlink <tt>/bin</tt> to <tt>/usr/bin</tt>, implicitly forwarding the prohibition. Additionally, the files contained herein are not executables but are library code that clearly belong under <tt>/lib</tt> or <tt>/share</tt>.
# Which option is selected is left to discussion. One of the <tt>/lib</tt> choices is probably more conformant, but would make these modules accessible from a standard Python shell, which may not be desirable (except for SlicerWizard).
# For a standard installation, all products should be installed to <tt>${PREFIX}</tt>; <tt><product>_PREFIX=${Slicer_PREFIX}/lib/<product></tt> is non-standard.
# Convention for third party Qt plugins (e.g. see KDE) is a subdirectory (e.g. <tt>plugins</tt>) of <tt>/lib/<product></tt>.
# These non-executable files do not belong in <tt>/bin</tt>. While the <tt>.ini</tt> could possible be placed in <tt>/etc</tt>, this requires special handling in the case that <tt>PREFIX=/usr</tt>; <tt>/share/Slicer-<Version></tt> also seems like a reasonable location and does not have this issue.

Section references in the above are given for [http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.pdf the PDF version of FHS 2.3]. (The HTML version unfortunately does not number sections.)

Documentation/Labs/ExtensionsFrameworkRoadmap

2014-03-28T21:16:09Z

Matthew.woehlke: /* Progress */

This page serves as roadmap for the Slicer Extensions framework.

= Extension contribution process =

The goal here is to simplify the number of steps allowing people to contribute extension.

More specifically, we would like to make it very easy for people to create a python extension by:
* removing the need for a Slicer build tree
* reducing the number of steps required to create and load an extension from a template
* simplifying how an extension is contributed to the index
* simplifying how an extension can be uploaded to the extension server

== Current process ==

The current process to create an empty extension is documented [[Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions|here]], then the steps to contribute the extension are documented [[Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File|here]].

For all type of extension (C++ or python), the steps can then be summarized as:

=== To create an extension ===
# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''5 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

=== To save extension code ===
# Github: Create an account
# Github: Create a repository
# Workstation -> Github: Push local work on Github

=== To contribute an extension to Index ===
# SlicerWiki: Create documentation page
# Extension Server: Create an account
# Extension Server: Join community
# Extension Server: Ask permission for experimental folder.
# Workstation: Configure upload credential
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Github: Fork ExtensionsIndex
# Workstation: Clone fork locally
# Workstation: Create branch add-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Push the topic to fork
# Github: Click on Pull request button

=== To update an extension in Index ===
# SlicerWiki: Update documentation page
# Workstation: In extension index clone: '''5 commands to type'''
# Workstation: Create branch update-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Create pull request manually creating the URL
# Github: Add a comment in the pull request with a Compare link also manually generated

== Proposed changes ==

=== To create an extension ===

For all type of extensions, the simplified workflow is:

# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''1 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

For scripted extensions, creation directly from within Slicer:

# Slicer: Modules -> Developer -> ExtensionWizard
# ExtensionWizard module: Set name, description, contributors etc ... then click on Create
## Set the working directory ? Where to create.
## External link to the github account creation page (will open web browswer or tab in the extension manager ?)
## Optionally create github repo and pre-populate repo ...
# Path to the module(s) in extension should be added to the additional module path.
# Slicer: Restart - 'Foo' module should show up. ''Note: This last step could probably be removed''

=== To save extension code ===

For all type of extensions, the simplified workflow is:

# Github: Create an account
# Workstation -> Github: Create repository done with '''1 command'''. <code>ExtensionWizard.py --publish ~/code/MyExtension</code>

For scripted extensions:

# initial publish on github done from the ExtensionWizard module. See above

=== To publish extension code update===

For all type of extensions, the workflow is:

# git commit, ..., git push

=== To contribute an extension to the Index ===
# SlicerWiki: Create documentation page.
## Need to check with BHW if wiki version can be updated so that any IP could use the mediawiki API
# Extension Server: Create an account [Join community + experimental folder permission consolidated in one location]
## Create a "Slicer Extensions" community where user have to request access
## Folks belonging to the "Slicer Extensions" would be automatically be granted access
## Jc: Check with Midas team with user can request access to community
# Workstation: Configure upload credential
## Update [[Documentation/Nightly/Developers/Tutorials/ObtainExtensionServerApiKey|documentation]] to explain that MIDAS_API_* variable can be set in the env.
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Add extension to the index using '''1 command''': <code>ExtensionWizard.py --contribute --target master ~/code/MyExtension</code>

== Progress ==

* Improve Wizard to create empty extension: reduce number of terminal commands to 1
** [http://na-mic.org/Mantis/view.php?id=3566 3566: Wizard: Simplify creation of extensions/modules]: {{done}} Completed - Review in progress
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add ExtensionWizard wiki page]: {{done}} Completed - Review in progress -See [[Documentation/Nightly/Developers/ExtensionWizard]]
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add developer documentation for ExtensionWizard]: {{done}} Completed - Review in progress - See [http://mwoehlke-kitware.github.io/Slicer/SlicerWizard/]
* Publish extension on Github by creating github repo - {{done}} Completed - Review in progress

* In case of Python extension, remove the need for a Slicer build tree: '''50%'''
** Wizard: Remove dependency on build tree or CMake generated file. {{done}} - Review in progress
** Add install rules for the template source code - To make them available from an installed Slicer
** [http://na-mic.org/Mantis/view.php?id=3269 3269: Simplify contribution of scripted extension]: '''50%'''
** Slicer: Creation of python extension directly from within Slicer. '''ToBeDone'''
*** Slicer: Optional Restart. '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3603 3603 Slicer: Creation of python extension directly from Slicer.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3604 3604 ExtensionServer: Consolidate ExtensionsIndex account creation.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3605 3605 SlicerWiki: Automatic creation of extension wiki page.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3606 3606 Slicer: Given an extension python script. Should be possible to upload the extension directly from Slicer.] '''ToBeDone'''

= Extensions Catalog / Manager =

The goal here is to improve the overall user experience associated with the extension catalog.

When accessed from within Slicer the catalog is also referred as extensions manager.

== Progress ==

* [http://na-mic.org/Mantis/view.php?id=3564 3564: Add search option in extension manager]. {{review}} '''Awaiting Review'''
* [http://na-mic.org/Mantis/view.php?id=3602 3602: ExensionsManager - Add a "Show url" link']. {{review}} '''Awaiting Review'''
* [http://na-mic.org/Mantis/view.php?id=2089 2089: Either on-demand or when slicer starts, check if there are available extensions update.]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=3607 3607: ExtensionManager: Exclude category "Example" from "All" listing ].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2779 2779: Mechanism to keep track of the installed extensions across version]. '''ToBeDone'''

* Low priority:
** [http://na-mic.org/Mantis/view.php?id=2334 2334: Differentiate different type of extenions in extension manager: Concept of channel]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=2778 2778: Add "Download stats" on each extension page ]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=3608 3608: ExtensionsManager: Display description for installed extensions.]. Code complete, waiting on [http://na-mic.org/Mantis/view.php?id=3564 3564] to be merged
** Consolidate rating across extension version. See [https://github.com/midasplatform/slicerappstore/issues/9#issuecomment-15643678 midasplatform/slicerappstore/issues/9]

= Extension developer documentation =

The goal is to consolidate the existing documentation so that it is easy to understand what is the python API available to the Slicer python extension developer.

== Progress ==

* Generate Slicer python API documentation. '''In progress'''. See experiment http://mwoehlke-kitware.github.io/Slicer/Base/

Template:Review

2014-03-26T18:13:51Z

Matthew.woehlke: Created page with '<includeonly> </includeonly><noinclude> == Usage == <pre>{{Review}}</pre> {{Review}} {{PAGENAME}} </noinclude>'

<includeonly>[[Image:Review.png|16px| ]]</includeonly><noinclude>
== Usage ==
<pre>{{Review}}</pre>
{{Review}}

[[Category:Templates|{{PAGENAME}}]]
</noinclude>

Documentation/Labs/ExtensionsFrameworkRoadmap

2014-03-26T18:13:03Z

Matthew.woehlke: /* Progress */

This page serves as roadmap for the Slicer Extensions framework.

= Extension contribution process =

The goal here is to simplify the number of steps allowing people to contribute extension.

More specifically, we would like to make it very easy for people to create a python extension by:
* removing the need for a Slicer build tree
* reducing the number of steps required to create and load an extension from a template
* simplifying how an extension is contributed to the index
* simplifying how an extension can be uploaded to the extension server

== Current process ==

The current process to create an empty extension is documented [[Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions|here]], then the steps to contribute the extension are documented [[Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File|here]].

For all type of extension (C++ or python), the steps can then be summarized as:

=== To create an extension ===
# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''5 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

=== To save extension code ===
# Github: Create an account
# Github: Create a repository
# Workstation -> Github: Push local work on Github

=== To contribute an extension to Index ===
# SlicerWiki: Create documentation page
# Extension Server: Create an account
# Extension Server: Join community
# Extension Server: Ask permission for experimental folder.
# Workstation: Configure upload credential
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Github: Fork ExtensionsIndex
# Workstation: Clone fork locally
# Workstation: Create branch add-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Push the topic to fork
# Github: Click on Pull request button

=== To update an extension in Index ===
# SlicerWiki: Update documentation page
# Workstation: In extension index clone: '''5 commands to type'''
# Workstation: Create branch update-YourExtensionName
# Workstation: Commit description file obtained from build tree
# Workstation -> Github: Create pull request manually creating the URL
# Github: Add a comment in the pull request with a Compare link also manually generated

== Proposed changes ==

=== To create an extension ===

For all type of extensions, the simplified workflow is:

# Workstation: Build Slicer application in Release
# Workstation: Use the Wizard to create an extension '''1 commands to enter in a terminal'''
# Workstation: Initialize git repository '''1 command'''
# Workstation: Implement extension / local commits

For scripted extensions, creation directly from within Slicer:

# Slicer: Modules -> Developer -> ExtensionWizard
# ExtensionWizard module: Set name, description, contributors etc ... then click on Create
## Set the working directory ? Where to create.
## External link to the github account creation page (will open web browswer or tab in the extension manager ?)
## Optionally create github repo and pre-populate repo ...
# Path to the module(s) in extension should be added to the additional module path.
# Slicer: Restart - 'Foo' module should show up. ''Note: This last step could probably be removed''

=== To save extension code ===

For all type of extensions, the simplified workflow is:

# Github: Create an account
# Workstation -> Github: Create repository done with '''1 command'''. <code>ExtensionWizard.py --publish ~/code/MyExtension</code>

For scripted extensions:

# initial publish on github done from the ExtensionWizard module. See above

=== To publish extension code update===

For all type of extensions, the workflow is:

# git commit, ..., git push

=== To contribute an extension to the Index ===
# SlicerWiki: Create documentation page.
## Need to check with BHW if wiki version can be updated so that any IP could use the mediawiki API
# Extension Server: Create an account [Join community + experimental folder permission consolidated in one location]
## Create a "Slicer Extensions" community where user have to request access
## Folks belonging to the "Slicer Extensions" would be automatically be granted access
## Jc: Check with Midas team with user can request access to community
# Workstation: Configure upload credential
## Update [[Documentation/Nightly/Developers/Tutorials/ObtainExtensionServerApiKey|documentation]] to explain that MIDAS_API_* variable can be set in the env.
# Workstation -> ExtensionServer: Test upload [1 command to enter in a terminal / 1 click in visual studio]
# Add extension to the index using '''1 command''': <code>ExtensionWizard.py --contribute --target master ~/code/MyExtension</code>

== Progress ==

* Improve Wizard to create empty extension: reduce number of terminal commands to 1
** [http://na-mic.org/Mantis/view.php?id=3566 3566: Wizard: Simplify creation of extensions/modules]: {{done}} Completed - Review in progress
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add ExtensionWizard wiki page]: {{done}} Completed - Review in progress -See [[Documentation/Nightly/Developers/ExtensionWizard]]
** [http://na-mic.org/Mantis/view.php?id=3572 3572: Add developer documentation for ExtensionWizard]: {{done}} Completed - Review in progress - See [http://mwoehlke-kitware.github.io/Slicer/SlicerWizard/]
* Publish extension on Github by creating github repo - {{done}} Completed - Review in progress

* In case of Python extension, remove the need for a Slicer build tree: '''50%'''
** Wizard: Remove dependency on build tree or CMake generated file. {{done}} - Review in progress
** Add install rules for the template source code - To make them available from an installed Slicer
** [http://na-mic.org/Mantis/view.php?id=3269 3269: Simplify contribution of scripted extension]: '''50%'''
** Slicer: Creation of python extension directly from within Slicer. '''ToBeDone'''
*** Slicer: Optional Restart. '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3603 3603 Slicer: Creation of python extension directly from Slicer.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3604 3604 ExtensionServer: Consolidate ExtensionsIndex account creation.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3605 3605 SlicerWiki: Automatic creation of extension wiki page.] '''ToBeDone'''

* [http://na-mic.org/Mantis/view.php?id=3606 3606 Slicer: Given an extension python script. Should be possible to upload the extension directly from Slicer.] '''ToBeDone'''

= Extensions Catalog / Manager =

The goal here is to improve the overall user experience associated with the extension catalog.

When accessed from within Slicer the catalog is also referred as extensions manager.

== Progress ==

* [http://na-mic.org/Mantis/view.php?id=3564 3564: Add search option in extension manager]. {{review}} '''Awaiting Review'''
* [http://na-mic.org/Mantis/view.php?id=3602 3602: ExensionsManager - Add a "Show url" link']. '''ToBeDone'''
* [http://na-mic.org/Mantis/view.php?id=2089 2089: Either on-demand or when slicer starts, check if there are available extensions update.]. '''ToBeDone'''
* <s>[http://na-mic.org/Mantis/view.php?id=3607 3607: ExtensionManager: Exclude category "Example" from "All" listing ].</s> {{done}} '''Completed'''
* [http://na-mic.org/Mantis/view.php?id=2779 2779: Mechanism to keep track of the installed extensions across version]. '''ToBeDone'''

* Low priority:
** [http://na-mic.org/Mantis/view.php?id=2334 2334: Differentiate different type of extenions in extension manager: Concept of channel]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=2778 2778: Add "Download stats" on each extension page ]. '''ToBeDone'''
** [http://na-mic.org/Mantis/view.php?id=3608 3608: ExtensionsManager: Display description for installed extensions.]. Code complete, waiting on [http://na-mic.org/Mantis/view.php?id=3564 3564] to be merged
** Consolidate rating across extension version. See [https://github.com/midasplatform/slicerappstore/issues/9#issuecomment-15643678 midasplatform/slicerappstore/issues/9]

= Extension developer documentation =

The goal is to consolidate the existing documentation so that it is easy to understand what is the python API available to the Slicer python extension developer.

== Progress ==

* Generate Slicer python API documentation. '''In progress'''. See experiment http://mwoehlke-kitware.github.io/Slicer/Base/

File:Review.png

2014-03-26T18:10:23Z

Matthew.woehlke: [http://www.inkscape.org/ Inkscape] rendered version of Review.svg, as the server is not rendering it correctly.

[http://www.inkscape.org/ Inkscape] rendered version of [[:File:Review.svg|Review.svg]], as the server is not rendering it correctly.

File:Review.svg

2014-03-26T17:38:54Z

Matthew.woehlke:

File:Check.svg

2014-03-26T16:59:33Z

Matthew.woehlke: uploaded a new version of "File:Check.svg"

Template:Done

2014-03-26T16:55:25Z

Matthew.woehlke:

<includeonly>[[Image:Check.svg|16px| ]]</includeonly><noinclude>
== Usage ==
<pre>{{Done}}</pre>
{{Done}}

[[Category:Templates|{{PAGENAME}}]]
</noinclude>

File:Check.svg

2014-03-26T16:52:26Z

Matthew.woehlke:

Documentation/Nightly/Developers/Tutorials/SelfTestModule

2014-03-26T14:57:42Z

Matthew.woehlke: /* Goal */ fix wrong-version link

<noinclude>{{documentation/versioncheck}}</noinclude>
== Goal ==

After [http://www.na-mic.org/Wiki/index.php/2012_Summer_Project_Week:SelfTesting review and work by the slicer community], a framework is in place that supports Built In Self Tests for slicer.

Important features include:
* Tests are available as part of the binary distributions of slicer, so users can confirm correct behavior on their systems
* The same tests are run as part of the nightly test process and submitted to [http://slicer.cdash.org/index.php?project=Slicer4 the slicer dashboard].
* Developers can efficiently develop the tests by reloading python scripts without needing to exit slicer.

This page provides an overview of the implementation and use of these scripts.

The approach described here can be used in a number of ways:
* When developing a new scripted module, you can create a test script at the same time. This way you can use the script to help you test the code as you develop it (by reloading and testing as you write the code without even exiting slicer) and also verify that your code still works as you refactor and improve the code. Plus, you can easily test the code on multiple platforms without a lot of tedious clicking to reload data.
* Self Tests of the core slicer functionality can be used equally in build-time and run-time scenarios.
* [[Documentation/{{documentation/version}}/Developers/Modules|Any type of module or extension]] can also include self tests (and should!).

== Caveats ==
This project is actively evolving and is being worked on and some of the implementation details will change in future versions.

These instructions assume you are working with a local build of slicer.

== Creating the Skeleton ==

=== Use the ModuleWizard ===
Start by using the [[Documentation/{{documentation/version}}/Developers/ModuleWizard|module wizard]] to create a new scripted module.

Give the module a descriptive name based on the functionality you intend to test. If the module is created to recreated the steps described in a bug report, append the bug report name to the end of the test. For example, one test is [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/SlicerApp/Testing/Python/sceneImport2428.py?view=markup sceneImport2428.py] which tests [http://www.na-mic.org/Bug/view.php?id=2428 issue #2428].

At first, put the new module in a dedicated directory:

cd <Slicer source dir>
./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../NeurosurgeryTutorial NeurosurgeryTutorial

This will create a new extension directory with a skeleton NeurosurgeryTutorial.py file ready to work on.

=== Edit the new module ===
In the editor, change a few of the fields:

Change:
parent.categories = ["Examples"]
to:
parent.categories = ["Testing.TestCases"]

Also change the contributor names, the acknowledgement text, and any other general fields to customize the module.

=== Configure Slicer ===
In slicer, go into the Application Settings->Module Settings and add a path to the NeurosurgeryTutorial directory and restart slicer.

=== Restart Slicer and Test ===

When slicer comes back up you should find your module in the Modules->Testing->TestCases menu.

If you click the Reload and Test button, a default test will run and it should pass.

You are now ready to customize this test for your own use.

== Test Data ==

Test data should be uploaded [http://slicer.kitware.com slicer's midas instance]. If you need to upload new data, consult the midas documentation to get an account and request access to the NA-MIC community.

Toward the bottom of your python script (in the method test_NeurosurgeryTutorial1) you can see how data is downloaded from midas and loaded into slicer. In the template, a single volume file is downloaded:

downloads = (
('http://slicer.kitware.com/midas3/download?items=5767', 'FA.nrrd', slicer.util.loadVolume),
)

[http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/SlicerApp/Testing/Python/ other self test scripts] load multiple datasets and/or scene files.

Note that the current test template will re-use any existing file in the temp directory that has non-zero size. If you change the test data, give it a new name for the download.

=== Accessing Test Data Through A Firewall ===

The SelfTest modules use python urllib to download data. If you are behind a firewall, you can configure urllib to use a proxy server by setting the environment variable

export http_proxy=http://proxyhost:proxyport

Note the use of "http://" at the start of the url. The environment variable http_proxy is also used by git and wget but they do not require the "http://" but will accept it if there.

== Writing/Refining the Code ==

Note that you can click the Reload and Test button as many times as you want and to re-run the test.

Now, you can experiment with changing the code. Add another line to the beginning of the test_NeurosurgeryTutorial1 method like:

self.delayDisplay("My modified test")

Save the file and click Reload and Test. You should see your new message as a dialog and you should also see it printed in the console.

From here, you "only" need to implement the python code that performs your test. For that, you can rely on the python wrappings of Qt, VTK, numpy, etc. [http://www.slicer.org/slicerWiki/index.php/Slicer4:Python Python in Slicer4]

To open up the GUI for a specific module, for instance the Volumes modules, you can use:

m = slicer.util.mainWindow()
m.moduleSelector().selectModule('Volumes')
self.delayDisplay("Entered Volumes module")

=== Screen shots ===

To capture screen shots, when the Enable Screenshots button in the GUI is clicked, or the default setting is changed in your code , then add this line after parts of your code that sets up the GUI into configurations that you want to capture:

self.takeScreenshot('TestName-ScreenshotName','Screenshot description',-1)

The last argument defines what parts of Slicer to capture, -1 is for the whole window, you can also use these options:

slicer.qMRMLScreenShotDialog().FullLayout
slicer.qMRMLScreenShotDialog().ThreeD
slicer.qMRMLScreenShotDialog().Red
slicer.qMRMLScreenShotDialog().Yellow
slicer.qMRMLScreenShotDialog().Green

To enable screen shots by default, change this line:

self.enableScreenshotsFlagCheckBox.checked = 0

to:

self.enableScreenshotsFlagCheckBox.checked = 1

== Adding the Result to Slicer ==

When you are satisfied that your test captures the intended functionality, you can add it to the main repository (or, if you don't have write access, coordinate with a developer who does have write access).

To make this a self test, copy the NeurosurgeryTutorial.py into Applications/SlicerApp/Testing/Python/ and edit the Applications/SlicerApp/Testing/Python/CMakeLists.txt file.

In the SelfTests section, add a line like:

slicer_add_python_unittest(SCRIPT NeurosurgeryTutorial.py)

and add NeurosurgeryTutorial.py to the KIT_PYTHON_SCRIPTS list.

== That's it! ==

Now your test will be run as part of the nightly dashboard process and will be available to users so they can verify that your code is operating as designed on their platform.

Documentation/Nightly/Developers/FAQ/Extensions

2014-03-17T18:48:21Z

Matthew.woehlke: /* Where can I find the extension templates ? */ Point to new Extension Wizard

<noinclude>{{documentation/versioncheck}}</noinclude>
<noinclude>__TOC__
={{#titleparts: {{PAGENAME}} | | -1 }}=</noinclude><includeonly>
='''Developer FAQ: {{{1}}}'''=
</includeonly>

== Should the name of the source repository match the name of the extension ? ==

Assuming your extension is named <code>AwesomeFilter</code>, generally, we suggest to name the extension repository either <code>SlicerAwesomeFilter</code>, <code>Slicer-AwesomeFilter</code>, <code>Slicer_AwesomeFilter</code>, <code>SlicerExtension-AwesomeFilter</code>, <code>SlicerExtension_AwesomeFilter</code>.

Doing so will minimize confusion by clearly stating that the code base is associated with Slicer.

== What is the Extensions Index ? ==

{{:Documentation/{{documentation/version}}/Developers/Extensions/Index}}

== What is an API Key ? ==

See http://en.wikipedia.org/wiki/Application_programming_interface_key

== How to obtain an API key to submit on the extension server ? ==
{{:Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey}}

== Where can I find the extension templates ? ==

The module and extension templates are available in the Slicer source tree: https://github.com/Slicer/Slicer/tree/master/Utilities/Templates/

Using the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]], you could easily create a new extension without having to copy, rename and update manually every files.

== How to build an extension ? ==

Assuming that the source code of your extension is located in folder <code>MyExtension</code>, this could be achieved doing:

{|width = "100%"
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Makefile
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Visual Studio
|-
| valign="top" |
{{pre2|<nowiki>
$ mkdir MyExtension-build
$ cd MyExtension-build
$ cmake -DCMAKE_BUILD_TYPE:STRING=Release -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension
$ make</nowiki>
}}
| valign="top" |
<ol start="1" style="list-style-type: decimal;">
<li>Start CMake, select source and build directory</li>
<li>Add <code>Slicer_DIR</code> entry to the cache</li>
<li>Click on <code>Configure</code>, select generator, then click on <code>Generate</code> button.</li>
<li>Open <code>MyExtension.sln</code>, select <code>Release</code> configuration, then menu <code>Project -> Build Solution</code>.</li>
</ol>
|}

== How to package an extension ? ==

Assuming your extension has been built into folder <code>MyExtension-build</code>, this could be achieved doing:

{|width = "100%"
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Makefile
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Visual Studio
|-
| valign="top" |
{{pre2|<nowiki>
$ make package
</nowiki>
}}
| valign="top" |
<ol start="1" style="list-style-type: decimal;">
<li>Open <code>MyExtension.sln</code></li>
<li>Select <code>PACKAGES</code> project, then right click and select <code>Build</code></li>
</ol>
|}

== How to upload an extension ? ==

<ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
<li>{{:Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions/ExperimentalFolderAccess}}</li>
</ol>

Assuming your extension has been built and packaged into folder <code>MyExtension-build</code>, this could be achieved by first re-configuring the project providing your [[#How_to_obtain_an_API_key_to_submit_on_the_extension_server_.3F|midas credentials]] and then building the <code>ExperimentalUploadOnly</code> target:

{|width = "100%"
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Makefile
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Visual Studio
|-
| valign="top" |
{{pre2|<nowiki>
$ cmake -DMIDAS_PACKAGE_EMAIL:STRING=<YOUR-MIDAS-LOGIN> -DMIDAS_PACKAGE_API_KEY:STRING=<YOUR-MIDAS-APIKEY> .
$ make ExperimentalUploadOnly
</nowiki>
}}
| valign="top" |
<ol start="1" style="list-style-type: decimal;">
<li>Start CMake, select source and build directory</li>
<li>Add <code>MIDAS_PACKAGE_EMAIL</code> and <code>MIDAS_PACKAGE_API_KEY</code> entries to the cache</li>
<li>Open <code>MyExtension.sln</code></li>
<li>Select <code>Release</code> configuration</li>
<li>Select <code>ExperimentalUploadOnly</code> project, then right click and select <code>Build</code></li>
</ol>
|}

== What are the extension specific targets: ExperimentalUpload, ExperimentalUploadOnly, ... ? ==

Slicer extension build system provides the developer with a set of convenient targets allowing to build and upload extensions.

<table class="alternate">
<tr>
<th>Target name</th>
<th>Description</th>
</tr>
<tr>
<td><code>Experimental</code></td>
<td>Configure, build, test the extension and publish result on CDash.</td>
</tr>
<tr>
<td><code>ExperimentalUpload</code></td>
<td>Equivalent to Experimental target followed by packaging and upload of the extension on the extension server.</td>
</tr>
<tr>
<td><code>ExperimentalUploadOnly</code></td>
<td>Only proceed to the upload of the extension on the extension server.</td>
</tr>
<tr>
<td><code>test</code> or <code>BUILD_TESTS</code></td>
<td>Locally execute the test</td>
</tr>
<tr>
<td><code>package</code> or <code>PACKAGE</code></td>
<td>Locally package the extension</td>
</tr>
</table>

== Is --launch flag available for a MacOSX installed Slicer.app ?==

On MacOSx, running Slicer with the --help argument does NOT list the usual launcher related options.

$ ./Slicer.app/Contents/MacOS/Slicer --help
Usage
Slicer [options]

Options
--, --ignore-rest Ignores the rest of the labeled arguments following this flag. (default: false)
-h, --help Display available command line arguments.
[...]
--version Displays version information and exits.

To provide some background information, when generating the package that will be distributed, an application bundle <code>Slicer.app</code> is created. As explained [http://developer.apple.com/library/mac/#documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html here], a bundle is a directory with a standardized hierarchical structure that holds executable code and the resources used by that code. It means that since all libraries contained within a bundle are referenced relatively to the location of either the CLI or the Slicer executable, the use of launcher does NOT make sens.

To help fixing-up the libraries, executables and plugins so that they reference each other in a relative way, CMake provides us with the [http://www.cmake.org/cmake/help/v2.8.8/cmake.html#module:BundleUtilities BundleUtilities] module.

This module is used in two situations:
# Fixup of Slicer application itself. See [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerCPack.cmake#L36-68 SlicerCPack.cmake#L36-68] and [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerCPackBundleFixup.cmake.in SlicerCPackBundleFixup.cmake.in]
# Fixup of an extension package. See [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerExtensionCPack.cmake#L126-143 SlicerExtensionCPack.cmake#L126-143] and [https://github.com/Slicer/Slicer/blob/master/CMake/SlicerExtensionCPackBundleFixup.cmake.in SlicerExtensionCPackBundleFixup.cmake.in]

== What is the difference between Documentation/Nightly/Modules and Documentation/Nightly/Extensions ? ==

As suggested by the namespace names:
* All module documentation pages should be located under <code>Documentation/Nightly/Modules</code>
* All extension documentation pages should be located under <code>Documentation/Nightly/Extensions</code>

For example, if an an extension named <code>DoSomethingGreat</code> bundles three modules <code>ModuleA</code>, <code>ModuleB</code> and <code>ModuleC</code>. The following pages should be created:
* <code>Documentation/Nightly/Extensions/DoSomethingGreat</code>
* <code>Documentation/Nightly/Modules/ModuleA</code>
* <code>Documentation/Nightly/Modules/ModuleB</code>
* <code>Documentation/Nightly/Modules/ModuleC</code>

In case your extension bundles only one module, the extension name is expected to match the module name. For example, if your extension is named <code>DoSomethingAwesome</code>, the associated module is expected to be named <code>DoSomethingAwesome</code>. The following pages will then be created:
* <code>Documentation/Nightly/Extensions/DoSomethingAwesome</code>
* <code>Documentation/Nightly/Modules/DoSomethingAwesome</code>
where page <code>Extensions/DoSomethingAwesome</code> redirect to page <code>Modules/DoSomethingAwesome</code>.

To setup a redirection, simply add the following text to page <code>Extensions/DoSomethingAwesome</code>:
<pre>
#REDIRECT [[Documentation/Nightly/Modules/DoSomethingAwesome]]
</pre>
For an example, see [http://www.slicer.org/slicerWiki/index.php?title=Documentation/Nightly/Extensions/SkullStripper&action=edit here]

More details about redirection are available here: http://www.mediawiki.org/wiki/Help:Redirects

== Which URL should be associated with EXTENSION_HOMEPAGE metadata ? ==

Extensions available through the Slicer Extensions Catalog are expected to have a page created under the <code>Nightly</code> documentation namespace. The corresponding URL should be associated with the <code>EXTENSION_HOMEPAGE</code> metadata.

For example:
* <code><nowiki>set(EXTENSION_HOMEPAGE "http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/DoSomethingGreat")</nowiki></code>
* <code><nowiki>set(EXTENSION_HOMEPAGE "http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/DoSomethingAwesome")</nowiki></code>

Note that this also apply for extension bundling only one module. Indeed, in this case the page will redirect to the appropriate module page. For example: http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/SkullStripper

== How to rename an extension to add new features ? ==

If you created an extension to perform Task1, but later on, your module is getting more generic and you add some other tasks, the name of your extension might change.
In order to rename, your extension, you should:
* Remove your old extension from the ExtensionsIndex
* Then, submit your extension again (including new features) with a new name
* Make also sure to add redirection from the "deprecated" module documentation to the "new" pages. On the Slicer wiki, this could be using the [http://www.mediawiki.org/wiki/Help:Redirects #REDIRECT] instruction.

== How to check if an extension is built by Slicer Extensions build system ? ==

Sometimes an extension could be built either as a standalone package or as a Slicer extension.

To differenciate the two cases, the developer could check for the value of:
<pre>
<ExtensionName>_BUILD_SLICER_EXTENSION
</pre>

This variable will be set to ON when the extension is built by the Slicer Extensions build system.

For details: https://github.com/Slicer/Slicer/blob/ff5f5a866d8afcaa0f2e6f615cc8f8cf07361741/Extensions/CMake/SlicerBlockBuildPackageAndUploadExtension.cmake#L95

== How often extensions are uploaded on the extensions server ? ==

Slicer extensions are built and uploaded on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]] every day.

To be more specific, the frequency of extensions build and upload associated with:
* Slicer nightly package occurs '''every night''' and also '''continuously''' during the day.
* Slicer {{documentation/currentversion}} lastest stable release package occurs '''every night'''.

== Will an extension be uploaded if associated tests are failing ? ==

Independently of the extension test results, if the extension could be successfully packaged, it will be uploaded on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]].

Documentation/Nightly/Developers/ModuleWizard

2014-03-14T20:34:17Z

Matthew.woehlke: mark as deprecated, direct to Extension Wizard instead

<noinclude>{{documentation/versioncheck}}</noinclude>

{{ambox
| type = warning
| text = '''Deprecated'''This page describes a utility which has been deprecated. If you are using Slicer 4.4 or later, it is recommended to use the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]] instead.
}}

 

== Background ==

Slicer modules typically consist of several files of various types, such as CMake files, source files, and binary 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.

Also, it is not uncommon to want to use one module as the starting point for implementing similar functionality.

For development, we suggest starting with the structure of an Extension that can contains one or more modules. The [[Documentation/{{documentation/version}}/Developers/Modules|modules]] can be of different types, such as python scripted module or pure C++ modules or a combination.

The ModuleWizard will do most of the copying and renaming for you, but you will also need to manually configure some steps (specifically, you need to edit the CMakeLists.txt file when you add a module to an extension).

== Terminology ==

* The ''template'' is a directory containing a slicer module
* The ''templateKey'' is a text string, typically the name of the module, that is used in both filename and identifiers inside the module.
* The ''target'' is a directory where you want the new module to be placed
* The ''moduleName'' is the string that you want to use in place of the ''templateKey''

== Usage ==

ModuleWizard [--template <dir>] [--templateKey <key>] [--target <dir>] <moduleName>
--template default ./Extensions/Testing/LoadableExtensionTemplate
--templateKey default is dirname of template
--target default ./Modules/Loadable/<moduleName>

== Step by Step ==

The idea of the wizard is to create a new self-contained directory that is a working module from the slicer perspective. This means that for C++ extensions, you only need to compile the extension and it will work with slicer. For scripted (python) extensions, you don't even need to compile.

Running this wizard will create the module in the specified target directory and will give it the name you specify on the command line.

=== Creating an Extension ===

For example, running this command:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate --target ../MyExtension MyExtension

should be done from within the slicer source directory, so that the <code>ModuleWizard.py</code> script is found, and so that the template path points to the correct spot. This command relies on your machine having an installed python interpreter to run the wizard (any version of python should work, you don't need to use the one that gets built with slicer).

This command will create a new directory parallel to the Slicer source directory, in this case called MyExtension.

The resulting extension will include a sample module in a directory called "ScriptedLoadableModuleTemplate" -- ''you should delete this directory since we will replace it in the next step.''

Edit the MyExtension/CMakeLists.txt file to customize it for your work. For example, list yourself and your colleagues as contributors and add the proper links to your project pages and icons. You should also make a custom icon for extension, that will represent it in the ExtensionManager.

=== Adding a Module ===

Instead of the generic module, we'll want a new one with a custom name, you can use the ModuleWizard again to rename the file and the contents from the template:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../MyExtension/MyScriptedModule MyScriptedModule

Now you will need to edit the ../MyExtension/CMakeLists.txt and change the following line:

add_subdirectory(ScriptedLoadableModuleTemplate)

to read:

add_subdirectory(MyScriptedModule)

Since we used the ScriptedLoadableExtensionTemplate, the only thing we need to do is set the additional module path to point to the full path to MyExtension/MyScriptedModule in the [[Documentation/{{documentation/version}}/SlicerApplication/ApplicationSettings|Application Settings]] dialog.

Then when you restart slicer, you should select your module using in the [[Documentation/{{documentation/version}}/SlicerApplication/MainApplicationGUI#Module_Selection_.26_Navigation|Module Navigation]] interface.

=== Adding More Modules ===

Note that you can repeat the steps for adding modules so that your extension can contain many modules of different types. Just run the ModuleWizard with the path to the appropriate template, and add the directory to the CMakeLists.txt.

== Examples ==

To create a [[Documentation/{{documentation/version}}/Developers/Modules#Command_Line_Interface_.28CLI.29|CLI]] Extension:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/CLIExtensionTemplate/CLIModuleTemplate --target ../MyExtension/MyCLIModule MyCLIModule

where <code>MyFooExtension</code> is the name of your extension

To create a [[Documentation/{{documentation/version}}/Developers/Tutorials/CreateLoadableModule|Loadable]] Module:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/LoadableExtensionTemplate/LoadableModuleTemplate --target ../MyExtension/MyLoadableModule MyLoadableModule

To create a [[Documentation/{{documentation/version}}/Developers/Modules#Scripted_Modules|Scripted Loadable]] Module:

./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/ScriptedLoadableExtensionTemplate/ScriptedLoadableModuleTemplate --target ../MyExtension/MyScriptedModule MyScriptedModule

To create an [[Documentation/{{documentation/version}}/Developers/EditorExtension|EditorEffect]] Extension
./Utilities/Scripts/ModuleWizard.py --template ./Extensions/Testing/EditorExtensionTemplate/EditorEffectTemplate --target ../MyExtension/MyEditorEffect MyEditorEffect

For reference, an extension directory that results from the steps above can be found [https://github.com/pieper/MyExtension in this git repository].

=== Creating and Testing a Loadable Module ===

The following code can be run from the SuperBuild directory (mac and linux):

<pre>
NEWMODULE=NewModule
SLICERSUPERBUILD=`pwd`

../Slicer/Utilities/Scripts/ModuleWizard.py --template ../Slicer/Extensions/Testing/LoadableExtensionTemplate --target /tmp/${NEWMODULE} ${NEWMODULE}
mkdir /tmp/${NEWMODULE}-build
(cd /tmp/${NEWMODULE}-build; cmake /tmp/${NEWMODULE} -DSlicer_DIR:PATH=${SLICERSUPERBUILD}/Slicer-build; make)
./Slicer-build/Slicer --additional-module-paths /tmp/${NEWMODULE}-build/lib/Slicer-4.2/qt-loadable-modules

</pre>

After running this command, Slicer will start, and you will find the default LoadableModuleTempate in the modules menu under Examples. In the python interpreter, you can access the wrapped logic with:

logic = slicer.modules.loadablemoduletemplate.logic()

From here, you can add additional methods to the logic and develop the GUI.

''Note: use the latest version of CMake (2.8.11) on mac''

Documentation/Nightly/Developers/Modules

2014-03-14T20:11:01Z

Matthew.woehlke: change module wizard references to point to new extension wizard instead

<noinclude>{{documentation/versioncheck}}</noinclude>
Slicer supports three types of modules. While the developer has to choose between one of the three types to implement its module, the end user won't notice the difference as they all share the same look & feel. The choice for a given type of module is usually based on the type of inputs/parameters for a given module.

= Command Line Interface (CLI) =
CLIs are standalone executables with a limited input/output arguments complexity (simple argument types, no user interactions...). They are typically implemented using [http://www.itk.org ITK].
* Shared lib or executable
* UI automatically generated
* Where to start ?
# Create initial skeleton using the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]]
# Read [[Documentation/{{documentation/version}}/Developers/Build_Module|Compiling slicer modules outside of the slicer source tree.]]
# Learn from [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Modules/CLI/ existing modules]
* Links:
** [[Slicer3:Execution_Model_Documentation|Slicer3 execution model]] (Slicer4 is very similar)
** [http://www.na-mic.org/Wiki/index.php/File:Slicer4_CLI.ppt CLI in Slicer4] (presentation of 2012 NAMIC AHM)

= Loadable Modules =
Loadable modules are [http://en.wikipedia.org/wiki/C%2B%2B C++] plugins that are built against Slicer. They define custom GUIs for their specific behavior as they have full control over the application.
* C++ shared library
* Full control over the UI (based on [http://qt.nokia.com/products/ Qt]) and Slicer internals (MRML, logics, display managers...)
* Optimized for heavy computations
* Where to start ?
# Create initial skeleton using the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]]
# Read [[Documentation/{{documentation/version}}/Developers/Build_Module|Compiling slicer modules outside of the slicer source tree.]]
# Learn from [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Modules/Loadable/ existing modules]
* Links:
**[http://www.na-mic.org/Wiki/index.php/File:LoadableModules.pptx Loadable modules] (presentation of 2012 NAMIC AHM)
**[[Documentation/{{documentation/version}}/Developers/Tutorials/CreateLoadableModule|How to write a loadable module]]

= Scripted Modules =
Scripted modules are written in [http://www.python.org/ Python].

An extensive tutorial and reference page was created [http://www.na-mic.org/Wiki/index.php/2013_Project_Week_Breakout_Session:Slicer4Python for the Slicer/Python breakout session at the NA-MIC 2014 Summer Project Week]. Please read through this and many of your questions will be answered.

* Python Console
* Full access to the API: [http://www.vtk.org VTK], MRML, [http://qt.nokia.com/products/ Qt] and Slicer are fully wrapped
* Recommended for fast prototyping
* Where to start ?
# Read the [http://www.na-mic.org/Wiki/index.php/2013_Project_Week_Breakout_Session:Slicer4Python Slicer/Python breakout session at the NA-MIC 2014 Summer Project Week] tutorial.
# Create initial skeleton using the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension Wizard]]
# Read [[Documentation/{{documentation/version}}/Developers/Build_Module|Compiling slicer modules outside of the slicer source tree.]]
# Learn from [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Modules/Scripted/ existing modules]
* Links:
** [http://www.slicer.org/slicerWiki/index.php/Documentation/{{documentation/version}}/Developers/Python_scripting Python Scripting]
** [[Documentation/{{documentation/version}}/Training#Slicer4_Programming_Tutorial|Python Scripting Tutorial]]

=Module Factory=
Loading modules into slicer happens in multiple steps:
*module factories must be registered into the factory manager
* directories where the modules to load are located must be passed to the factory manager
* Optionally specify module names to ignore
* scan the directories and test which file is a module and register it (not instantiated yet)
* Instantiate all the register modules
* Connect each module with the scene and the application
More details can be found in the [http://slicer.org/doc/html/classqSlicerAbstractModuleFactoryManager.html online doc]

==ToDo==
* Transform all core modules into Loadable modules.
** the factory manager only support file based modules, core modules are not file based (linked into the core factory itself)
* Move factory registration in qSlicerApplication (or a general application library) to support module discovery/loading without needing to instantiate Slicer.
** Currently can't be moved into qSlicerApplication as the CLI factories that are in QTCLI depend on QTGUI
** QtTesting is also limited with the QTCLI dependency on QtGUI (->qSlicerApplication would need to access QtTesting code from QtCli)
** Proposed architecture
Base
Application -> classes that are useful to build an application (mix of qSlicerCoreApplication, qSlicerApplication, Main.cxx...)
Core -> formally QtCore
Modules -> contains the factories and module specific code
Loadable
CLI
Scripted
Scripted -> all that is python specific
Cxx
Python
Widgets -> formally QtGUI
* Add category hierarchy in the Settings module panel
* Register factory settings/command-options(e.g. disable-loadable-modules) when registering module factories
** To have the settings panel be generic but have the code proper of each registered factory somewhere else
* Add mechanism for modules to register dialogs (toolbars that open dialogs), e.g. the sceneview module needs to register the sceneView dialog into an icon.
* Ignore modules from the launcher command line.
* cloning" of module panels at run time. See [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2012/008965.html "here] and [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2012/008039.html here]

Documentation/Nightly/Developers/Versioning

2014-03-14T19:26:23Z

Matthew.woehlke: /* Release */ improve step organization

<noinclude>{{documentation/versioncheck}}</noinclude>


= Versioning =

== Project fork ==

While Slicer specific patches related to dependent project (i.e. VTK) are integrated upstream, it is not uncommon to build Slicer against a Slicer specific fork of the project.

For example: https://github.com/Slicer/VTK

=== Patches for tagged release ===

For each version of the project requiring some specific patches, a branch following that convention will be created: <code>slicer-vX.Y.Z</code> where <code>X.Y.Z</code> corresponds to the version of the project.

For example, in case of the SlicerVTK fork, the branch <code>slicer-v5.10.1</code> has been created.

=== Patches for development branch ===

In this case, since there is no tag associated with the branch, the Slicer specific patch should be added to a branch named using the date of the commit parent of the Slicer branch: <code>slicer-YEAR-MONTH-DAY-vX.Y</code> where <code>X.Y</code> corresponds to the fork release.

== Create release dashboard scripts ==

{{wip}}

== Feature freeze ==

Usually ~1 month before release.

== Prerequisites ==

* Update modules documentation link in help section (loadable, scripted and cli)
** And some html links in Welcome module (Modules/Loadable/SlicerWelcome/Resources/HTML)
** Update CLI XML description files

Commit message: <code>Update Documentation to X.Y</code>

For example: [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22407 r22407]

== Release-candidate ==

Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.

<code><RC></code> corresponds to the release candidate number. It is greater or equal to one.

<ol start="1" style="list-style-type: decimal;">

<li>Update the Slicer version information for the release candidate:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, uncomment and set:
*<code>Slicer_VERSION_TWEAK</code> to <code>0</code>
*<code>Slicer_VERSION_RC</code> to <code><RC></code>
...and if this is the first release candidate, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
<li>Commit the above changes using this message:
ENH: Slicer X.Y.Z-rc<RC>
</li>
</ol>
</li>

<li>Generate packages based on REVISION associated with step 1.</li>

<li>Update the Slicer version information for the development:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, comment <code>Slicer_VERSION_TWEAK</code> so that the next builds will contain the date associated with the last commit.</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
</li>
<li>Commit the above changes using this message:
ENH: Begin post-X.Y.Z-rc<RC> development
</li>
</ol>

</ol>

== Release ==

Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.

<ol start="1" style="list-style-type: decimal;">

<li>Update the Slicer version information for the release:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, uncomment and set <code>Slicer_VERSION_TWEAK</code> to <code>0</code>
...and if this no release candidate has been made, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
<li>Commit the above changes using this message:
ENH: Slicer X.Y.Z
</li>
</ol>
</li>

<li>Generate packages based on REVISION associated with step 1.

<li>Tag the repository:
svn copy -r<REVISION> http://svn.slicer.org/Slicer4/trunk \
http://svn.slicer.org/Slicer4/tags/Slicer-X-Y \
-m "ENH: Tag of X.Y.Z release based on r<REVISION>."
</li>

<li>Update the Slicer version information for the development:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, comment and set:
* <code>Slicer_VERSION_TWEAK</code> to <code>0</code> so that the next builds will contain the date associated with the last commit.
* <code>Slicer_VERSION_RC</code> to <code>0</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
<li>Commit the above changes using this message:
ENH: Begin post-X.Y.Z development
</li>
</ol>
</li>

</ol>

== Post release ==

=== Create a release branch ===

svn copy -r <REVISION> http://svn.slicer.org/Slicer4/trunk http://svn.slicer.org/Slicer4/branches/Slicer-X-Y \
-m "ENH: Branching from trunk to Slicer-X-Y at <REVISION>"

svn checkout http://svn.slicer.org/Slicer4/branches/Slicer-X-Y

=== Generate ChangeLog ===

* See [https://raw.github.com/cryos/avogadro/master/scripts/gitlog2changelog.py gitlog2changelog.py]. More details [http://blog.cryos.net/archives/202-Git-and-Automatic-ChangeLog-Generation.html here].

* Update [[Release Details]] page using generated ChangeLog

=== Update Mantis ===

* "Release" current target
* Create new target
* Check the "fixed in" fields

=== Midas ===

==== Tag release packages ====

* If needed, create a X.Y.Z folder in [http://slicer.kitware.com/midas3/folder/274 Slicer/Packages/Application/Release]
** Copy uploaded packages into the folder created above
** Identify the item_id associated with uploaded packages. For example: 11926, 11925, 11927, 11992
** SSH connect to <code>jcfr@slicer.kitwarein.com</code>
** Connect to mysql using <code>mysql -u midas -p</code>
*** See file <code>/var/www/midas3/core/configs/database.local.ini</code> for password
*** Choose midas database: <code>use midas</code>
** List packages associated with identified items and check they are the appropriate ones:
*** <code>select * from slicerpackages_package as p , item as i where i.item_id = p.item_id and p.item_id in (11926, 11925, 11927, 11992);</code>
** Set release field
*** <code>update slicerpackages_package set `release`="4.2.2-1" where item_id in (11926, 11925, 11927, 11992);</code>

==== Version NA-MIC data tree ====

<ol start="1" style="list-style-type: decimal;">

<li>[[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|Create an account on the extension server and obtain an API Key]]. You will then use your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples.</li>

<li>If not already done, go to [http://slicer.kitware.com/midas3/community/23 NA-MIC community] and click on <code>Join community</code></li>

<li>Send an email on the developer list asking to be added to the <code>DataManager</code> group on NA-MIC community. That will grant you read/write permissions to the <code>Data</code> folder and sub-folders.</li>

<li>Install prerequisites
<pre>
$ sudo pip install pydas
</pre></li>

<li>Identify <code>id</code> of the <code>Data</code> folder. For example [http://slicer.kitware.com/midas3/folder/301 301]</li>

<li>Simulate creation of <code>X.Y</code> data folders based <code>Nightly</code> ones
<pre>
$ cd /path/to/Slicer/Base/Python/slicer/release
$ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
--email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y --dry-run
Application ( folder_id: 302 )
'-Nightly ( folder_id: 831 )
'-'-Testing ( folder_id: 832 )
'-'-'-Baseline ( folder_id: 889 )
'-'-'-'-DiffusionTensorImagingTutorial.png ( item_id: 12067 )
'-'-'-'-NeurosurgicalPlanningTutorial.png ( item_id: 12066 )
'-'-'-'-SlicerTestingTest.png ( item_id: 17760 )
'-'-'-Input ( folder_id: 833 )
'-'-'-'-AtlasTests ( folder_id: 834 )
'-'-'-'-'-2012-10-26-BrainAtlas.mrb ( item_id: 10276 )
[...]
Module: VotingBinaryHoleFillingImageFilter ( folder_id: 1491 )
'-Nightly ( folder_id: 1491 )
'-'-Testing ( folder_id: 1492 )
'-'-'-Baseline ( folder_id: 1493 )
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.nhdr ( item_id: 103418 )
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.raw.gz ( item_id: 103419 )

</pre>
</li>

<li>Create <code>X.Y</code> data tree based <code>Nightly</code> ones
<pre>
$ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
--email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y

Versioning of the NA-MIC Data tree for release X.Y...
Versioning Modules...
[...]
Versioning Modules...[DONE]
Versioning Application...
Creating folder X.Y under Application directory
Duplicating subfolders from Nightly to X.Y...
Duplicating subfolders from Nightly to X.Y...[DONE]
Versioning Application...[DONE]
Versioning of the NA-MIC Data tree for release X.Y...[DONE]

</pre></li>

</ol>

=== Update Slicer wiki ===

The copy of the pages associated with the <code>Nightly</code> namespace into the <code>X.Y</code> namespace is done using the convenience python module [https://github.com/jcfr/mwdoc#readme mwdoc].

<ol start="1" style="list-style-type: decimal;">

<li>Check with <email>jchris.fillionr@kitware.com</email> to get the credential associated with <code>UpdateBot</code> user.</li>

<li>
Copy <code>Nightly</code> pages into <code>X.Y</code> pages.
<pre>
$ cd ~/Projects

$ sudo pip install mwclient

$ git clone git://github.com/jcfr/mwdoc

$ cd mwdoc

$ python

>>> import mwdoc
>>> doc = mwdoc.Documentation('slicer.org', '/slicerWiki/')
>>> doc.login('UpdateBot', 'XXXXXXX')
>>> doc.versionPages('Nightly', '4.3', ['Documentation', 'Template:Documentation'])
[INFO] Page successfully created: 'Documentation/4.3/Extensions/ErodeDilateLabel'
[...]
[INFO] Page successfully created: 'Template:Documentation/4.3/module-header'
[INFO] Page successfully created: 'Template:Documentation/4.3/module-section'
[INFO] Page successfully created: 'Template:Documentation/4.3/module/footer'
</pre>
</li>

<li>Update [[Template:Documentation/nextversion]]</li>

<li>Update [[Template:Documentation/currentversion]]</li>

<li>Update [[Template:Documentation/versionlist]]</li>

<li>Update [[FAQ]]</li>

<li>Update [[Documentation]]</li>

<li>Update [[Documentation/Release]]</li>

<li>Update [[Documentation/Release/Announcements]]</li>

<li>Update [[Documentation/UserTraining]]</li>

<li>Update [[Documentation/UserOrientation]]</li>

<li>Update [[Documentation/DeveloperOrientation]]</li>
</ol>

=== CDash ===

<ol start="1" style="list-style-type: decimal;">
<li>Create new CDash groups for extension submissions associated with <code>X.Y</code> release:
<pre>
Extensions-X.Y-Nightly
Extensions-X.Y-Continuous
</pre></li>

</ol>

=== Update external website ===

* http://en.wikipedia.org/wiki/3DSlicer
* http://www.nitrc.org/projects/slicer/

=== Backport commit into release branch ===

The following steps will lead to the creation of new git-svn clone having two branches:
* <code>git-svn</code>
* <code>git-svn-XY</code>

Reference: http://www.dmo.ca/blog/20070608113513/

==== Step 1: Checkout sources ====

git clone git://github.com/Slicer/Slicer.git Slicer-X.Y
cd Slicer-X.Y
git svn init http://svn.slicer.org/Slicer4/trunk
git update-ref refs/remotes/git-svn refs/remotes/origin/master
git checkout master
git svn rebase

==== Step 2: Add release branch remote ====

Edit <code>.git/config</code>, and in addition to the existing 'git-svn' remote, add the following one:

[svn-remote "svn-XY"]
url = http://svn.slicer.org/Slicer4/branches/Slicer-X-Y
fetch = :refs/remotes/git-svn-XY

==== Step 3: Pull associated SVN branch ====

git svn fetch svn-XY
git checkout -b master-XY git-svn-XY

==== Step 4: Backport ====

We can now cherry pick commit associated with master (trunk) into <code>master-XY</code> (Slicer-X-Y)

==== Step 5: Create a patch release ====

{{wip}}



= Slicer Package naming scheme =
{{ambox|text=The following information is for Slicer maintainers only}}

<pre>Slicer-<MAJOR_VERSION>.<MINOR_VERSION>.<PATCH_VERSION>[-rc{1|2|3...}][-<TWEAK_VERSION>][-<DATE>][-svn<REV>][-dirty]-<ARCH>-<PLATFORM></pre>

There are 2 types of builds, releases and developments:
; Release
: Special builds made on a given revision (e.g. r19033: "ENH: Slicer 4.0.1")
: Don't contain date or revision number.
: The optional suffix '''-rc{1|2|3|...}''' identifies the release candidates leading to a final release.
: Eventually, a tweak number can be added (e.g. 4.0.1-1)
; Development
: Nightly or experimental builds
: Contains suffixes after the major.minor.patch version
: The suffix '''svn<REV>''' allows to identify the revision associated with the current package.
: The '''-dirty''' prefix indicates if the package has been generated from a locally modified source tree.

== Example of linux 64bits packages ==
[ File name ][ date ][ build type ][ note ]
Slicer-4.0.0-linux-amd64 2011-11-24 release release of Slicer 4.0.0
Slicer-4.0.0-2011-12-10-linux-amd64 2011-11-25 development nightly build after 4.0.0
Slicer-4.0.1-rc1-linux-amd64 2012-01-04 release release candidate 1 of Slicer 4.0.1
Slicer-4.0.1-rc1-2012-01-05-linux-amd64 2012-01-05 development nightly build after the release candidate
Slicer-4.0.1-rc2-linux-amd64 2012-01-11 release release candidate 2 of Slicer 4.0.1
Slicer-4.0.1-rc2-2012-01-12-linux-amd64 2012-01-12 development nightly build after the release candidate
Slicer-4.0.1-linux-amd64 2012-01-14 release release of Slicer 4.0.1
Slicer-4.0.1-2012-01-20-linux-amd64 2012-01-20 development nightly build after 4.0.1
Slicer-4.0.1-1-linux-amd64 2012-01-28 release tweak version 1 of Slicer 4.0.1
Slicer-4.0.2-linux.amd64 2012-06-05 release release of Slicer 4.0.2

= Extension package - Naming scheme =

* Create <code>Extensions-XYZ-Nightly</code> and <code>Extensions-XYZ-Continuous</code> tracks on CDash

*

Documentation/Nightly/Developers/Versioning

2014-03-14T19:24:21Z

Matthew.woehlke: /* Release-candidate */ document update process for __version__.py, improve step organization

<noinclude>{{documentation/versioncheck}}</noinclude>


= Versioning =

== Project fork ==

While Slicer specific patches related to dependent project (i.e. VTK) are integrated upstream, it is not uncommon to build Slicer against a Slicer specific fork of the project.

For example: https://github.com/Slicer/VTK

=== Patches for tagged release ===

For each version of the project requiring some specific patches, a branch following that convention will be created: <code>slicer-vX.Y.Z</code> where <code>X.Y.Z</code> corresponds to the version of the project.

For example, in case of the SlicerVTK fork, the branch <code>slicer-v5.10.1</code> has been created.

=== Patches for development branch ===

In this case, since there is no tag associated with the branch, the Slicer specific patch should be added to a branch named using the date of the commit parent of the Slicer branch: <code>slicer-YEAR-MONTH-DAY-vX.Y</code> where <code>X.Y</code> corresponds to the fork release.

== Create release dashboard scripts ==

{{wip}}

== Feature freeze ==

Usually ~1 month before release.

== Prerequisites ==

* Update modules documentation link in help section (loadable, scripted and cli)
** And some html links in Welcome module (Modules/Loadable/SlicerWelcome/Resources/HTML)
** Update CLI XML description files

Commit message: <code>Update Documentation to X.Y</code>

For example: [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22407 r22407]

== Release-candidate ==

Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.

<code><RC></code> corresponds to the release candidate number. It is greater or equal to one.

<ol start="1" style="list-style-type: decimal;">

<li>Update the Slicer version information for the release candidate:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, uncomment and set:
*<code>Slicer_VERSION_TWEAK</code> to <code>0</code>
*<code>Slicer_VERSION_RC</code> to <code><RC></code>
...and if this is the first release candidate, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
<li>Commit the above changes using this message:
ENH: Slicer X.Y.Z-rc<RC>
</li>
</ol>
</li>

<li>Generate packages based on REVISION associated with step 1.</li>

<li>Update the Slicer version information for the development:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, comment <code>Slicer_VERSION_TWEAK</code> so that the next builds will contain the date associated with the last commit.</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
</li>
<li>Commit the above changes using this message:
ENH: Begin post-X.Y.Z-rc<RC> development
</li>
</ol>

</ol>

== Release ==

Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.

<ol start="1" style="list-style-type: decimal;">

<li>Update the Slicer version information for the release:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, uncomment and set <code>Slicer_VERSION_TWEAK</code> to <code>0</code>
...and if this no release candidate has been made, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
</ol>
</li>

<li>Commit the above changes using this message:
ENH: Slicer X.Y.Z
</li>

<li>Generate packages based on REVISION associated with step1.
Tag the repository:
svn copy -r<REVISION> http://svn.slicer.org/Slicer4/trunk \
http://svn.slicer.org/Slicer4/tags/Slicer-X-Y \
-m "ENH: Tag of X.Y.Z release based on r<REVISION>."

</li>

<li>Update the Slicer version information for the development:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, comment and set:
* <code>Slicer_VERSION_TWEAK</code> to <code>0</code> so that the next builds will contain the date associated with the last commit.
* <code>Slicer_VERSION_RC</code> to <code>0</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
</ol>
</li>

<li>Commit the above changes using this message:
ENH: Begin post-X.Y.Z development
</li>

</ol>

== Post release ==

=== Create a release branch ===

svn copy -r <REVISION> http://svn.slicer.org/Slicer4/trunk http://svn.slicer.org/Slicer4/branches/Slicer-X-Y \
-m "ENH: Branching from trunk to Slicer-X-Y at <REVISION>"

svn checkout http://svn.slicer.org/Slicer4/branches/Slicer-X-Y

=== Generate ChangeLog ===

* See [https://raw.github.com/cryos/avogadro/master/scripts/gitlog2changelog.py gitlog2changelog.py]. More details [http://blog.cryos.net/archives/202-Git-and-Automatic-ChangeLog-Generation.html here].

* Update [[Release Details]] page using generated ChangeLog

=== Update Mantis ===

* "Release" current target
* Create new target
* Check the "fixed in" fields

=== Midas ===

==== Tag release packages ====

* If needed, create a X.Y.Z folder in [http://slicer.kitware.com/midas3/folder/274 Slicer/Packages/Application/Release]
** Copy uploaded packages into the folder created above
** Identify the item_id associated with uploaded packages. For example: 11926, 11925, 11927, 11992
** SSH connect to <code>jcfr@slicer.kitwarein.com</code>
** Connect to mysql using <code>mysql -u midas -p</code>
*** See file <code>/var/www/midas3/core/configs/database.local.ini</code> for password
*** Choose midas database: <code>use midas</code>
** List packages associated with identified items and check they are the appropriate ones:
*** <code>select * from slicerpackages_package as p , item as i where i.item_id = p.item_id and p.item_id in (11926, 11925, 11927, 11992);</code>
** Set release field
*** <code>update slicerpackages_package set `release`="4.2.2-1" where item_id in (11926, 11925, 11927, 11992);</code>

==== Version NA-MIC data tree ====

<ol start="1" style="list-style-type: decimal;">

<li>[[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|Create an account on the extension server and obtain an API Key]]. You will then use your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples.</li>

<li>If not already done, go to [http://slicer.kitware.com/midas3/community/23 NA-MIC community] and click on <code>Join community</code></li>

<li>Send an email on the developer list asking to be added to the <code>DataManager</code> group on NA-MIC community. That will grant you read/write permissions to the <code>Data</code> folder and sub-folders.</li>

<li>Install prerequisites
<pre>
$ sudo pip install pydas
</pre></li>

<li>Identify <code>id</code> of the <code>Data</code> folder. For example [http://slicer.kitware.com/midas3/folder/301 301]</li>

<li>Simulate creation of <code>X.Y</code> data folders based <code>Nightly</code> ones
<pre>
$ cd /path/to/Slicer/Base/Python/slicer/release
$ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
--email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y --dry-run
Application ( folder_id: 302 )
'-Nightly ( folder_id: 831 )
'-'-Testing ( folder_id: 832 )
'-'-'-Baseline ( folder_id: 889 )
'-'-'-'-DiffusionTensorImagingTutorial.png ( item_id: 12067 )
'-'-'-'-NeurosurgicalPlanningTutorial.png ( item_id: 12066 )
'-'-'-'-SlicerTestingTest.png ( item_id: 17760 )
'-'-'-Input ( folder_id: 833 )
'-'-'-'-AtlasTests ( folder_id: 834 )
'-'-'-'-'-2012-10-26-BrainAtlas.mrb ( item_id: 10276 )
[...]
Module: VotingBinaryHoleFillingImageFilter ( folder_id: 1491 )
'-Nightly ( folder_id: 1491 )
'-'-Testing ( folder_id: 1492 )
'-'-'-Baseline ( folder_id: 1493 )
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.nhdr ( item_id: 103418 )
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.raw.gz ( item_id: 103419 )

</pre>
</li>

<li>Create <code>X.Y</code> data tree based <code>Nightly</code> ones
<pre>
$ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
--email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y

Versioning of the NA-MIC Data tree for release X.Y...
Versioning Modules...
[...]
Versioning Modules...[DONE]
Versioning Application...
Creating folder X.Y under Application directory
Duplicating subfolders from Nightly to X.Y...
Duplicating subfolders from Nightly to X.Y...[DONE]
Versioning Application...[DONE]
Versioning of the NA-MIC Data tree for release X.Y...[DONE]

</pre></li>

</ol>

=== Update Slicer wiki ===

The copy of the pages associated with the <code>Nightly</code> namespace into the <code>X.Y</code> namespace is done using the convenience python module [https://github.com/jcfr/mwdoc#readme mwdoc].

<ol start="1" style="list-style-type: decimal;">

<li>Check with <email>jchris.fillionr@kitware.com</email> to get the credential associated with <code>UpdateBot</code> user.</li>

<li>
Copy <code>Nightly</code> pages into <code>X.Y</code> pages.
<pre>
$ cd ~/Projects

$ sudo pip install mwclient

$ git clone git://github.com/jcfr/mwdoc

$ cd mwdoc

$ python

>>> import mwdoc
>>> doc = mwdoc.Documentation('slicer.org', '/slicerWiki/')
>>> doc.login('UpdateBot', 'XXXXXXX')
>>> doc.versionPages('Nightly', '4.3', ['Documentation', 'Template:Documentation'])
[INFO] Page successfully created: 'Documentation/4.3/Extensions/ErodeDilateLabel'
[...]
[INFO] Page successfully created: 'Template:Documentation/4.3/module-header'
[INFO] Page successfully created: 'Template:Documentation/4.3/module-section'
[INFO] Page successfully created: 'Template:Documentation/4.3/module/footer'
</pre>
</li>

<li>Update [[Template:Documentation/nextversion]]</li>

<li>Update [[Template:Documentation/currentversion]]</li>

<li>Update [[Template:Documentation/versionlist]]</li>

<li>Update [[FAQ]]</li>

<li>Update [[Documentation]]</li>

<li>Update [[Documentation/Release]]</li>

<li>Update [[Documentation/Release/Announcements]]</li>

<li>Update [[Documentation/UserTraining]]</li>

<li>Update [[Documentation/UserOrientation]]</li>

<li>Update [[Documentation/DeveloperOrientation]]</li>
</ol>

=== CDash ===

<ol start="1" style="list-style-type: decimal;">
<li>Create new CDash groups for extension submissions associated with <code>X.Y</code> release:
<pre>
Extensions-X.Y-Nightly
Extensions-X.Y-Continuous
</pre></li>

</ol>

=== Update external website ===

* http://en.wikipedia.org/wiki/3DSlicer
* http://www.nitrc.org/projects/slicer/

=== Backport commit into release branch ===

The following steps will lead to the creation of new git-svn clone having two branches:
* <code>git-svn</code>
* <code>git-svn-XY</code>

Reference: http://www.dmo.ca/blog/20070608113513/

==== Step 1: Checkout sources ====

git clone git://github.com/Slicer/Slicer.git Slicer-X.Y
cd Slicer-X.Y
git svn init http://svn.slicer.org/Slicer4/trunk
git update-ref refs/remotes/git-svn refs/remotes/origin/master
git checkout master
git svn rebase

==== Step 2: Add release branch remote ====

Edit <code>.git/config</code>, and in addition to the existing 'git-svn' remote, add the following one:

[svn-remote "svn-XY"]
url = http://svn.slicer.org/Slicer4/branches/Slicer-X-Y
fetch = :refs/remotes/git-svn-XY

==== Step 3: Pull associated SVN branch ====

git svn fetch svn-XY
git checkout -b master-XY git-svn-XY

==== Step 4: Backport ====

We can now cherry pick commit associated with master (trunk) into <code>master-XY</code> (Slicer-X-Y)

==== Step 5: Create a patch release ====

{{wip}}



= Slicer Package naming scheme =
{{ambox|text=The following information is for Slicer maintainers only}}

<pre>Slicer-<MAJOR_VERSION>.<MINOR_VERSION>.<PATCH_VERSION>[-rc{1|2|3...}][-<TWEAK_VERSION>][-<DATE>][-svn<REV>][-dirty]-<ARCH>-<PLATFORM></pre>

There are 2 types of builds, releases and developments:
; Release
: Special builds made on a given revision (e.g. r19033: "ENH: Slicer 4.0.1")
: Don't contain date or revision number.
: The optional suffix '''-rc{1|2|3|...}''' identifies the release candidates leading to a final release.
: Eventually, a tweak number can be added (e.g. 4.0.1-1)
; Development
: Nightly or experimental builds
: Contains suffixes after the major.minor.patch version
: The suffix '''svn<REV>''' allows to identify the revision associated with the current package.
: The '''-dirty''' prefix indicates if the package has been generated from a locally modified source tree.

== Example of linux 64bits packages ==
[ File name ][ date ][ build type ][ note ]
Slicer-4.0.0-linux-amd64 2011-11-24 release release of Slicer 4.0.0
Slicer-4.0.0-2011-12-10-linux-amd64 2011-11-25 development nightly build after 4.0.0
Slicer-4.0.1-rc1-linux-amd64 2012-01-04 release release candidate 1 of Slicer 4.0.1
Slicer-4.0.1-rc1-2012-01-05-linux-amd64 2012-01-05 development nightly build after the release candidate
Slicer-4.0.1-rc2-linux-amd64 2012-01-11 release release candidate 2 of Slicer 4.0.1
Slicer-4.0.1-rc2-2012-01-12-linux-amd64 2012-01-12 development nightly build after the release candidate
Slicer-4.0.1-linux-amd64 2012-01-14 release release of Slicer 4.0.1
Slicer-4.0.1-2012-01-20-linux-amd64 2012-01-20 development nightly build after 4.0.1
Slicer-4.0.1-1-linux-amd64 2012-01-28 release tweak version 1 of Slicer 4.0.1
Slicer-4.0.2-linux.amd64 2012-06-05 release release of Slicer 4.0.2

= Extension package - Naming scheme =

* Create <code>Extensions-XYZ-Nightly</code> and <code>Extensions-XYZ-Continuous</code> tracks on CDash

*

Documentation/Nightly/Developers/Versioning

2014-03-14T19:15:57Z

Matthew.woehlke: /* Release */ document update process for __version__.py

<noinclude>{{documentation/versioncheck}}</noinclude>


= Versioning =

== Project fork ==

While Slicer specific patches related to dependent project (i.e. VTK) are integrated upstream, it is not uncommon to build Slicer against a Slicer specific fork of the project.

For example: https://github.com/Slicer/VTK

=== Patches for tagged release ===

For each version of the project requiring some specific patches, a branch following that convention will be created: <code>slicer-vX.Y.Z</code> where <code>X.Y.Z</code> corresponds to the version of the project.

For example, in case of the SlicerVTK fork, the branch <code>slicer-v5.10.1</code> has been created.

=== Patches for development branch ===

In this case, since there is no tag associated with the branch, the Slicer specific patch should be added to a branch named using the date of the commit parent of the Slicer branch: <code>slicer-YEAR-MONTH-DAY-vX.Y</code> where <code>X.Y</code> corresponds to the fork release.

== Create release dashboard scripts ==

{{wip}}

== Feature freeze ==

Usually ~1 month before release.

== Prerequisites ==

* Update modules documentation link in help section (loadable, scripted and cli)
** And some html links in Welcome module (Modules/Loadable/SlicerWelcome/Resources/HTML)
** Update CLI XML description files

Commit message: <code>Update Documentation to X.Y</code>

For example: [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22407 r22407]

== Release-candidate ==

Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.

<code><RC></code> corresponds to the release candidate number. It is greater or equal to one.

<ol start="1" style="list-style-type: decimal;">

<li>In <code>CMakeLists.txt</code>, uncomment and set:
*<code>Slicer_VERSION_TWEAK</code> to <code>0</code>
*<code>Slicer_VERSION_RC</code> to <code>1</code>, <code>2</code> or <code>3</code>

... and if this is the first release candidate, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>
</li>

<li>Commit <code>CMakeLists.txt</code> changes using this message:<pre>ENH: Slicer X.Y.Z-rc<RC></pre></li>

<li>Generate packages based on REVISION associated with step1.</li>

<li>
In <code>CMakeLists.txt</code>, comment <code>Slicer_VERSION_TWEAK</code> so that the next builds will contain the date associated with the last commit.
</li>

<li>
Commit <code>CMakeLists.txt</code> changes using this message: <pre>ENH: Begin post-X.Y.Z-rc<RC> development</pre>
</li>

</ol>

== Release ==

Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.

<ol start="1" style="list-style-type: decimal;">

<li>Update the Slicer version information for the release:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, uncomment and set <code>Slicer_VERSION_TWEAK</code> to <code>0</code>
...and if this no release candidate has been made, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
</ol>
</li>

<li>Commit the above changes using this message:
ENH: Slicer X.Y.Z
</li>

<li>Generate packages based on REVISION associated with step1.
Tag the repository:
svn copy -r<REVISION> http://svn.slicer.org/Slicer4/trunk \
http://svn.slicer.org/Slicer4/tags/Slicer-X-Y \
-m "ENH: Tag of X.Y.Z release based on r<REVISION>."

</li>

<li>Update the Slicer version information for the development:
<ol style="list-style-type: lower-roman;">
<li>In <code>CMakeLists.txt</code>, comment and set:
* <code>Slicer_VERSION_TWEAK</code> to <code>0</code> so that the next builds will contain the date associated with the last commit.
* <code>Slicer_VERSION_RC</code> to <code>0</code>
</li>
<li>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
</ol>
</li>

<li>Commit the above changes using this message:
ENH: Begin post-X.Y.Z development
</li>

</ol>

== Post release ==

=== Create a release branch ===

svn copy -r <REVISION> http://svn.slicer.org/Slicer4/trunk http://svn.slicer.org/Slicer4/branches/Slicer-X-Y \
-m "ENH: Branching from trunk to Slicer-X-Y at <REVISION>"

svn checkout http://svn.slicer.org/Slicer4/branches/Slicer-X-Y

=== Generate ChangeLog ===

* See [https://raw.github.com/cryos/avogadro/master/scripts/gitlog2changelog.py gitlog2changelog.py]. More details [http://blog.cryos.net/archives/202-Git-and-Automatic-ChangeLog-Generation.html here].

* Update [[Release Details]] page using generated ChangeLog

=== Update Mantis ===

* "Release" current target
* Create new target
* Check the "fixed in" fields

=== Midas ===

==== Tag release packages ====

* If needed, create a X.Y.Z folder in [http://slicer.kitware.com/midas3/folder/274 Slicer/Packages/Application/Release]
** Copy uploaded packages into the folder created above
** Identify the item_id associated with uploaded packages. For example: 11926, 11925, 11927, 11992
** SSH connect to <code>jcfr@slicer.kitwarein.com</code>
** Connect to mysql using <code>mysql -u midas -p</code>
*** See file <code>/var/www/midas3/core/configs/database.local.ini</code> for password
*** Choose midas database: <code>use midas</code>
** List packages associated with identified items and check they are the appropriate ones:
*** <code>select * from slicerpackages_package as p , item as i where i.item_id = p.item_id and p.item_id in (11926, 11925, 11927, 11992);</code>
** Set release field
*** <code>update slicerpackages_package set `release`="4.2.2-1" where item_id in (11926, 11925, 11927, 11992);</code>

==== Version NA-MIC data tree ====

<ol start="1" style="list-style-type: decimal;">

<li>[[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|Create an account on the extension server and obtain an API Key]]. You will then use your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples.</li>

<li>If not already done, go to [http://slicer.kitware.com/midas3/community/23 NA-MIC community] and click on <code>Join community</code></li>

<li>Send an email on the developer list asking to be added to the <code>DataManager</code> group on NA-MIC community. That will grant you read/write permissions to the <code>Data</code> folder and sub-folders.</li>

<li>Install prerequisites
<pre>
$ sudo pip install pydas
</pre></li>

<li>Identify <code>id</code> of the <code>Data</code> folder. For example [http://slicer.kitware.com/midas3/folder/301 301]</li>

<li>Simulate creation of <code>X.Y</code> data folders based <code>Nightly</code> ones
<pre>
$ cd /path/to/Slicer/Base/Python/slicer/release
$ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
--email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y --dry-run
Application ( folder_id: 302 )
'-Nightly ( folder_id: 831 )
'-'-Testing ( folder_id: 832 )
'-'-'-Baseline ( folder_id: 889 )
'-'-'-'-DiffusionTensorImagingTutorial.png ( item_id: 12067 )
'-'-'-'-NeurosurgicalPlanningTutorial.png ( item_id: 12066 )
'-'-'-'-SlicerTestingTest.png ( item_id: 17760 )
'-'-'-Input ( folder_id: 833 )
'-'-'-'-AtlasTests ( folder_id: 834 )
'-'-'-'-'-2012-10-26-BrainAtlas.mrb ( item_id: 10276 )
[...]
Module: VotingBinaryHoleFillingImageFilter ( folder_id: 1491 )
'-Nightly ( folder_id: 1491 )
'-'-Testing ( folder_id: 1492 )
'-'-'-Baseline ( folder_id: 1493 )
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.nhdr ( item_id: 103418 )
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.raw.gz ( item_id: 103419 )

</pre>
</li>

<li>Create <code>X.Y</code> data tree based <code>Nightly</code> ones
<pre>
$ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
--email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y

Versioning of the NA-MIC Data tree for release X.Y...
Versioning Modules...
[...]
Versioning Modules...[DONE]
Versioning Application...
Creating folder X.Y under Application directory
Duplicating subfolders from Nightly to X.Y...
Duplicating subfolders from Nightly to X.Y...[DONE]
Versioning Application...[DONE]
Versioning of the NA-MIC Data tree for release X.Y...[DONE]

</pre></li>

</ol>

=== Update Slicer wiki ===

The copy of the pages associated with the <code>Nightly</code> namespace into the <code>X.Y</code> namespace is done using the convenience python module [https://github.com/jcfr/mwdoc#readme mwdoc].

<ol start="1" style="list-style-type: decimal;">

<li>Check with <email>jchris.fillionr@kitware.com</email> to get the credential associated with <code>UpdateBot</code> user.</li>

<li>
Copy <code>Nightly</code> pages into <code>X.Y</code> pages.
<pre>
$ cd ~/Projects

$ sudo pip install mwclient

$ git clone git://github.com/jcfr/mwdoc

$ cd mwdoc

$ python

>>> import mwdoc
>>> doc = mwdoc.Documentation('slicer.org', '/slicerWiki/')
>>> doc.login('UpdateBot', 'XXXXXXX')
>>> doc.versionPages('Nightly', '4.3', ['Documentation', 'Template:Documentation'])
[INFO] Page successfully created: 'Documentation/4.3/Extensions/ErodeDilateLabel'
[...]
[INFO] Page successfully created: 'Template:Documentation/4.3/module-header'
[INFO] Page successfully created: 'Template:Documentation/4.3/module-section'
[INFO] Page successfully created: 'Template:Documentation/4.3/module/footer'
</pre>
</li>

<li>Update [[Template:Documentation/nextversion]]</li>

<li>Update [[Template:Documentation/currentversion]]</li>

<li>Update [[Template:Documentation/versionlist]]</li>

<li>Update [[FAQ]]</li>

<li>Update [[Documentation]]</li>

<li>Update [[Documentation/Release]]</li>

<li>Update [[Documentation/Release/Announcements]]</li>

<li>Update [[Documentation/UserTraining]]</li>

<li>Update [[Documentation/UserOrientation]]</li>

<li>Update [[Documentation/DeveloperOrientation]]</li>
</ol>

=== CDash ===

<ol start="1" style="list-style-type: decimal;">
<li>Create new CDash groups for extension submissions associated with <code>X.Y</code> release:
<pre>
Extensions-X.Y-Nightly
Extensions-X.Y-Continuous
</pre></li>

</ol>

=== Update external website ===

* http://en.wikipedia.org/wiki/3DSlicer
* http://www.nitrc.org/projects/slicer/

=== Backport commit into release branch ===

The following steps will lead to the creation of new git-svn clone having two branches:
* <code>git-svn</code>
* <code>git-svn-XY</code>

Reference: http://www.dmo.ca/blog/20070608113513/

==== Step 1: Checkout sources ====

git clone git://github.com/Slicer/Slicer.git Slicer-X.Y
cd Slicer-X.Y
git svn init http://svn.slicer.org/Slicer4/trunk
git update-ref refs/remotes/git-svn refs/remotes/origin/master
git checkout master
git svn rebase

==== Step 2: Add release branch remote ====

Edit <code>.git/config</code>, and in addition to the existing 'git-svn' remote, add the following one:

[svn-remote "svn-XY"]
url = http://svn.slicer.org/Slicer4/branches/Slicer-X-Y
fetch = :refs/remotes/git-svn-XY

==== Step 3: Pull associated SVN branch ====

git svn fetch svn-XY
git checkout -b master-XY git-svn-XY

==== Step 4: Backport ====

We can now cherry pick commit associated with master (trunk) into <code>master-XY</code> (Slicer-X-Y)

==== Step 5: Create a patch release ====

{{wip}}



= Slicer Package naming scheme =
{{ambox|text=The following information is for Slicer maintainers only}}

<pre>Slicer-<MAJOR_VERSION>.<MINOR_VERSION>.<PATCH_VERSION>[-rc{1|2|3...}][-<TWEAK_VERSION>][-<DATE>][-svn<REV>][-dirty]-<ARCH>-<PLATFORM></pre>

There are 2 types of builds, releases and developments:
; Release
: Special builds made on a given revision (e.g. r19033: "ENH: Slicer 4.0.1")
: Don't contain date or revision number.
: The optional suffix '''-rc{1|2|3|...}''' identifies the release candidates leading to a final release.
: Eventually, a tweak number can be added (e.g. 4.0.1-1)
; Development
: Nightly or experimental builds
: Contains suffixes after the major.minor.patch version
: The suffix '''svn<REV>''' allows to identify the revision associated with the current package.
: The '''-dirty''' prefix indicates if the package has been generated from a locally modified source tree.

== Example of linux 64bits packages ==
[ File name ][ date ][ build type ][ note ]
Slicer-4.0.0-linux-amd64 2011-11-24 release release of Slicer 4.0.0
Slicer-4.0.0-2011-12-10-linux-amd64 2011-11-25 development nightly build after 4.0.0
Slicer-4.0.1-rc1-linux-amd64 2012-01-04 release release candidate 1 of Slicer 4.0.1
Slicer-4.0.1-rc1-2012-01-05-linux-amd64 2012-01-05 development nightly build after the release candidate
Slicer-4.0.1-rc2-linux-amd64 2012-01-11 release release candidate 2 of Slicer 4.0.1
Slicer-4.0.1-rc2-2012-01-12-linux-amd64 2012-01-12 development nightly build after the release candidate
Slicer-4.0.1-linux-amd64 2012-01-14 release release of Slicer 4.0.1
Slicer-4.0.1-2012-01-20-linux-amd64 2012-01-20 development nightly build after 4.0.1
Slicer-4.0.1-1-linux-amd64 2012-01-28 release tweak version 1 of Slicer 4.0.1
Slicer-4.0.2-linux.amd64 2012-06-05 release release of Slicer 4.0.2

= Extension package - Naming scheme =

* Create <code>Extensions-XYZ-Nightly</code> and <code>Extensions-XYZ-Continuous</code> tracks on CDash

*

Documentation/Nightly/Developers/ExtensionWizard

2014-02-20T22:19:51Z

Matthew.woehlke: Add 'custom template' example, move templates information to correct section

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* '''For all operations:'''
** [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* '''For full functionality:'''
** [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
** [http://github.com/gitpython-developers/GitPython/ GitPython]
** [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[Documentation/{{documentation/version}}/Developers/Modules|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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <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
ExtensionWizard.py --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
<nowiki/>
# 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 [[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:

# "Publish" your extension by making it available on a publicly accessible repository.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''

{{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:

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.

{{notice|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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-20T20:54:28Z

Matthew.woehlke: Add additional tip, additional cross-reference link

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* '''For all operations:'''
** [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* '''For full functionality:'''
** [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
** [http://github.com/gitpython-developers/GitPython/ GitPython]
** [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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
<nowiki/>
# 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 [[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.

=== 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 [[Documentation/{{documentation/version}}/Developers/Modules|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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<your_user_name>''

{{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:

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.

{{notice|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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-18T23:11:10Z

Matthew.woehlke: /* Requirements */ git is now a "soft" dependency

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* '''For all operations:'''
** [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* '''For full functionality:'''
** [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
** [http://github.com/gitpython-developers/GitPython/ GitPython]
** [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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
<nowiki/>
# 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 [[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.

=== 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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<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.

{{notice|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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-14T23:20:11Z

Matthew.woehlke: /* Building */ Mention '-G' argument to CMake

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
* [http://github.com/gitpython-developers/GitPython/ GitPython]
* [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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
<nowiki/>
# 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 [[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.

=== 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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<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.

{{notice|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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-14T21:24:36Z

Matthew.woehlke: Update for new wizard behavior to prompt before changing extension information

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
* [http://github.com/gitpython-developers/GitPython/ GitPython]
* [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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.)

To build your extension:

Slicer_DIR=/path/to/slicer/superbuild
cd ~/code/MyExtension
mkdir ../MyExtension-build
cd ../MyExtension-build
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 [[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.

=== 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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<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.

{{notice|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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-13T20:21:45Z

Matthew.woehlke: add dependency install instructions

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
* [http://github.com/gitpython-developers/GitPython/ GitPython]
* [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 [http://www.macports.org/ MacPorts]:

sudo port install git-core

For Python and the Python dependencies, use of a Python [http://www.virtualenv.org/en/latest/ 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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.)

To build your extension:

Slicer_DIR=/path/to/slicer/superbuild
cd ~/code/MyExtension
mkdir ../MyExtension-build
cd ../MyExtension-build
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 [[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.

=== 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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<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.

{{notice|You should not use this command if your extension already has a public repository and/or is using Subversion for source code management.}}

Once your extension has a public repository, you should commit (svn) or push (git) changes using your SCM tool's usual workflow.

This command is intended to be used on new extensions, especially those created using the wizard (which initially have a placeholder homepage). If your extension already has a separate homepage that you would like to continue to use, you may wish to do the following after publishing:

vi CMakeLists.txt # or use your favorite editor to restore the old homepage
git add -p CMakeLists.txt
git commit --amend # Don't have other files staged when you do this!
git push origin +HEAD

This will amend the commit which changed your extension information and force-push the change to your new public github repository.

=== 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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-07T22:17:39Z

Matthew.woehlke:

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
* [http://github.com/gitpython-developers/GitPython/ GitPython]
* [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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.)

To build your extension:

Slicer_DIR=/path/to/slicer/superbuild
cd ~/code/MyExtension
mkdir ../MyExtension-build
cd ../MyExtension-build
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 [[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.

=== 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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<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.

{{notice|You should not use this command if your extension already has a public repository and/or is using Subversion for source code management.}}

Once your extension has a public repository, you should commit (svn) or push (git) changes using your SCM tool's usual workflow.

This command is intended to be used on new extensions, especially those created using the wizard (which initially have a placeholder homepage). If your extension already has a separate homepage that you would like to continue to use, you may wish to do the following after publishing:

vi CMakeLists.txt # or use your favorite editor to restore the old homepage
git add -p CMakeLists.txt
git commit --amend # Don't have other files staged when you do this!
git push origin +HEAD

This will amend the commit which changed your extension information and force-push the change to your new public github repository.

=== 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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-07T19:25:57Z

Matthew.woehlke: add documentation for contributing extensions, plus other minor tweaks

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* [http://www.python.org/ Python] ≥ 2.6 ('python' should be in your $PATH)
* [http://git-scm.com git] ≥ 1.7.10 (use [http://msysgit.github.io/ msys git] on Windows)
* [http://github.com/gitpython-developers/GitPython/ GitPython]
* [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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
<nowiki/>
# 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
<nowiki/>
# 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[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.

=== 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 <code>--templatePath</code> parameter:

# Add custom templates; expects to find subdirectories under the path matching
# a template type, e.g. 'modules'
ExtensionWizard.py --templatePath ~/code/Templates
<nowiki/>
# 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 <code>--templateKey</code> 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 [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.
# Request that your extension be added to the [http://github.com/Slicer/ExtensionsIndex public extension index].

Before you begin, you'll need a [http://github.com github] account.

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 you aren't using a password manager and want git to remember your user name, you may wish to run:

git config ''[''--global'']'' <nowiki>credential.https://github.com.username</nowiki> ''<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.

{{notice|You should not use this command if your extension already has a public repository and/or is using Subversion for source code management.}}

Once your extension has a public repository, you should commit (svn) or push (git) changes using your SCM tool's usual workflow.

This command is intended to be used on new extensions, especially those created using the wizard (which initially have a placeholder homepage). If your extension already has a separate homepage that you would like to continue to use, you may wish to do the following after publishing:

vi CMakeLists.txt # or use your favorite editor to restore the old homepage
git add -p CMakeLists.txt
git commit --amend # Don't have other files staged when you do this!
git push origin +HEAD

This will amend the commit which changed your extension information and force-push the change to your new public github repository.

=== 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
<nowiki/>
# If it does:
ExtensionWizard.py --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.

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

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.

Documentation/Nightly/Developers/ExtensionWizard

2014-02-06T20:31:13Z

Matthew.woehlke: initial documentation; just create/build for now

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


{{notice|For brevity, the remainder of this document assumes that ExtensionWizard.py, located in the <code>Utilities/Scripts</code> directory of your Slicer source directory, is in your $PATH.}}

=== Background ===

[[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 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 ===

* [http://www.python.org/ Python] >= 2.5 ('python' should be in your $PATH)
* [http://git-scm.com git] (use [http://msysgit.github.io/ msys git] on Windows)
* [https://github.com/gitpython-developers/GitPython/ GitPython]
* [http://jacquev6.github.io/PyGithub/ PyGithub]

You should also ensure that the python interpreter ('<code>python</code>') 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 <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>.)

Note that the destination (extension) directory is optional, defaulting to the current directory. In the above example, we <code>cd</code> 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 [[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.

=== 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 <code>--templatePath</code> 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 <code>--templateKey</code> 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.

Template:Notice

2014-02-06T17:48:38Z

Matthew.woehlke: Created page with '{{mbox | name = Notice | subst = <includeonly>{{subst:</includeonly><includeonly>substcheck}}</includeonly> | demospace = {{{demospace|}}} | image = {{#if:{{{image|}}}| [[Image:{…'

{{mbox
| name = Notice
| subst = <includeonly>{{subst:</includeonly><includeonly>substcheck}}</includeonly>
| demospace = {{{demospace|}}}
| image = {{#if:{{{image|}}}| [[Image:{{{image}}}|40px|Notice]] }}
| text =
{{#if:{{{header|}}}
| <div style="text-align:center;">'''{{{header}}}'''</div>
}}{{{1|{{{text}}}}}}
| small = {{{small|}}}
| smallimage = {{#if:{{{image|}}}| [[File:{{{image}}}|30px|Notice]] }}
}}<noinclude>

Imported from http://www.mediawiki.org/wiki/Template:Notice

{{documentation}}

</noinclude>