Documentation/Nightly/Developers/FAQ/Extensions

For the latest Slicer documentation, visit the read-the-docs.

Extensions

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

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

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

What is the Extensions Index ?

This page has been moved to read-the-docs.

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 ?

In order to upload extensions on the slicer extensions server, it is required to:

1. Create an account on the extension server: http://slicer.kitware.com by clicking on the Register link in the top right corner



This image shows the top portion of http://slicer.kitware.com after it has been expanded by clicking the Register button.

2. Go to NA-MIC community and click on Join community

3. Retrieve your API key looking at your account details:

   1. Go to http://slicer.kitware.com. If needed, signin by clicking on Login in the top right corner.
   2. Click on your name in the top right corner.
   3. Click on My account.
   4. Click on API tab.

   5. Copy the API Key associated with Default application.

      1. There is currently a bug preventing api key containing non alpanumeric characters from being used.
         If your Default api key contain for example a /, try to delete the api key and regenerate one that is not containing "/" and is named Default.
         We are working on the issue to update the build system so that it properly escape "/" and also get in touch with Midas team so that api key containing just number and letter are generated.

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 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 MyExtension, this could be achieved doing:

Makefile	Visual Studio
$ mkdir MyExtension-build $ cd MyExtension-build $ cmake -DCMAKE_BUILD_TYPE:STRING=Release -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension $ make	Start CMake, select source and build directory Add Slicer_DIR entry to the cache Click on Configure, select generator, then click on Generate button. Open MyExtension.sln, select Release configuration, then menu Project -> Build Solution.

How to package an extension ?

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

Makefile	Visual Studio
$ make package	Open MyExtension.sln Select PACKAGES project, then right click and select Build

How to upload an extension ?

1. If not already done, send an email on the slicer developers list asking to be granted write permission on the experimental folder.

   To: slicer-devel@bwh.harvard.edu
   Subject: Extension NAME-OF-YOUR-EXTENSION - Asking permission to write to the Experimental folder
   Hi, 
   
   This extension will allow to [...]
   
   Could you grant user YourUserName write access to the Experimental folder ?
   
   

Assuming your extension has been built and packaged into folder MyExtension-build, this could be achieved by first re-configuring the project providing your midas credentials and then building the ExperimentalUploadOnly target:

Makefile	Visual Studio
$ cmake -DMIDAS_PACKAGE_EMAIL:STRING=<YOUR-MIDAS-LOGIN> -DMIDAS_PACKAGE_API_KEY:STRING=<YOUR-MIDAS-APIKEY> . $ make ExperimentalUploadOnly	Start CMake, select source and build directory Add MIDAS_PACKAGE_EMAIL and MIDAS_PACKAGE_API_KEY entries to the cache Open MyExtension.sln Select Release configuration Select ExperimentalUploadOnly project, then right click and select Build

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.

Target name	Description
Experimental	Configure, build, test the extension and publish result on CDash.
ExperimentalUpload	Equivalent to Experimental target followed by packaging and upload of the extension on the extension server.
ExperimentalUploadOnly	Only proceed to the upload of the extension on the extension server.
test or BUILD_TESTS	Locally execute the test
package or PACKAGE	Locally package the extension

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 Slicer.app is created. As explained 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 BundleUtilities module.

This module is used in two situations:

1. Fixup of Slicer application itself. See SlicerCPack.cmake#L36-68 and SlicerCPackBundleFixup.cmake.in
2. Fixup of an extension package. See SlicerExtensionCPack.cmake#L126-143 and 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 Documentation/Nightly/Modules
• All extension documentation pages should be located under Documentation/Nightly/Extensions

For example, if an an extension named DoSomethingGreat bundles three modules ModuleA, ModuleB and ModuleC. The following pages should be created:

• Documentation/Nightly/Extensions/DoSomethingGreat
• Documentation/Nightly/Modules/ModuleA
• Documentation/Nightly/Modules/ModuleB
• Documentation/Nightly/Modules/ModuleC

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 DoSomethingAwesome, the associated module is expected to be named DoSomethingAwesome. The following pages will then be created:

• Documentation/Nightly/Extensions/DoSomethingAwesome
• Documentation/Nightly/Modules/DoSomethingAwesome

where page Extensions/DoSomethingAwesome redirect to page Modules/DoSomethingAwesome.

To setup a redirection, simply add the following text to page Extensions/DoSomethingAwesome:

#REDIRECT [[Documentation/Nightly/Modules/DoSomethingAwesome]]

For an example, see 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 Nightly documentation namespace. The corresponding URL should be associated with the EXTENSION_HOMEPAGE metadata.

For example:

• set(EXTENSION_HOMEPAGE "http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/DoSomethingGreat")
• set(EXTENSION_HOMEPAGE "http://slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/DoSomethingAwesome")

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

<ExtensionName>_BUILD_SLICER_EXTENSION

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 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 4.10 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 extensions server.