Slicer Extensions Index

Overview

Think of the ExtensionsIndex as a repository containing a list of extension description files (*.s4ext) used by the Slicer extensions build system to build, test, package and upload extensions on an extensions server.

Once uploaded on an extensions server, within Slicer, extensions can be installed using the extensions manager.

An extensions catalog provides Slicer users with a convenient way to access the extensions previously uploaded on the extensions server:

• from within Slicer with the help of the extensions manager
• from the web: http://slicer.kitware.com/midas3/slicerappstore

The rest of this document will provide the developer with detailed documentation, step-by-step instruction and also examples allowing to successfully test, package and upload extensions.

The following diagram depicts how extensions catalog, extensions server, CDash and the slicer factory interact.

Contributing

Extension description files

To contribute an extension description file, consider the following check list:

1. Extension belongs to Category 1 or Category 2 as described in Slicer requirements
2. Set up an account on the extension server and obtain an API key
3. Extension has been built and tested on the following platform: Linux, MacOSX and Windows. You could for example do an ExperimentalUpload and make sure the extension can be installed successfully. See manual build
4. Fork ExtensionIndex
5. Clone your fork, then create a topic named add-<ExtensionName>

git clone git@github.com:<yourlogin>/ExtensionsIndex SlicerExtensionsIndex
cd SlicerExtensionsIndex
git checkout -b add-<ExtensionName>

7. Commit your description file. Commit title should be Add <ExtensionName> extension and the content should provide details about the extension
8. Push the topic to your fork, then click on "Pull Request" button displayed on your github fork. Slicer folks will be automatically notified.
9. That's it !

Remarks:

• <ExtensionName> should be replaced with its actual value.

Dashboard submissions

Submission of experimental builds are welcome. See manual build instructions.

Submission of either continuous or nightly builds of extensions on Slicer CDash should be done solely by the slicer factory machine maintained by Kitware folks. While nothing prevent such submission from happening, it won't be possible to upload extensions on the extensions server without the appropriate credentials.

Prerequisites

• Slicer build tree >= 4.1.1 - r20313 - See slicer build instruction

Extensions build system

The extensions build system allows to drive the build, test, packaging and upload of slicer extensions.

Using the extensions build system source code living in the Slicer source tree, it is possible to build extensions using two different approaches:

1. Manual build
2. Dashboard driven build

Manual build

Relying on manual build provides a convenient way to:

• check extension description files are valid
• upload one or more extensions once to check that Slicer can download and install them

Given a directory containing one or more extension description files, it is possible to manually configure and build the associated extensions specifying the following CMake options:

Slicer_DIR	Path to Slicer build tree
Slicer_EXTENSION_DESCRIPTION_DIR	Path to folder containing extension description files

Optionally, it is also possible to specify:

CMAKE_BUILD_TYPE	On unix-like platform, should match the build type of the associated Slicer build directory
Slicer_UPLOAD_EXTENSIONS	By default set to OFF. If enabled, extension builds will be submitted to Slicer dashboard and associated packages will be uploaded to extensions server
MIDAS_PACKAGE_URL	MIDAS extensions server url specifying where the extension should be uploaded. For example http://slicer.kitware.com/midas3
MIDAS_PACKAGE_EMAIL	Email allowing to authenticate to the extensions server.
MIDAS_PACKAGE_API_KEY	Token allowing to authenticate to the extensions server.

Examples

The following examples are specific to unix-like platforms and can easily be adapted for windows.

Build your own set of extensions against Slicer trunk build tree

Considering the following assumptions:

1. Folder SlicerExtensionsCustomIndex contains the extension description files of your choice
2. Slicer trunk has been checkout into /path/to/Slicer-master and built into /path/to/Slicer-master-SuperBuild-Release
3. To upload extension(s) on the extensions server, an API key has been obtained.

The associated extensions could be built doing:

$ ls SlicerExtensionsCustomIndex
foo.s4ext
bar.s4ext
$ mkdir SlicerExtensionsCustomIndex-build
$ cd SlicerExtensionsCustomIndex-build
$ cmake -DSlicer_DIR:PATH=/path/to/Slicer-master-SuperBuild-Release/Slicer-build \
 -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsCustomIndex \
 -DCMAKE_BUILD_TYPE:STRING=Release \
 /path/to/Slicer-master/Extensions/CMake
$ make

Then, to submit the configure/build/test results on CDash Extensions-Experimental track and upload the extension on the extensions server of your choice, there are two options:

1. Build the target ExperimentalUpload associated with each extensions
2. Configure (or re-configure) the project passing the options Slicer_UPLOAD_EXTENSIONS, MIDAS_PACKAGE_URL, MIDAS_PACKAGE_EMAIL and MIDAS_PACKAGE_API_KEY

Extension build, test, package and upload using ExperimentalUpload target

$ cd SlicerExtensionsCustomIndex-build
$ cd foo-build
$ cmake -DMIDAS_PACKAGE_URL:STRING=http://slicer.kitware.com/midas3 \
 -DMIDAS_PACKAGE_EMAIL:STRING=jchris.fillionr@kitware.com \
 -DMIDAS_PACKAGE_API_KEY:STRING=a0b012c0123d012abc01234a012345a0 .
$ make ExperimentalUpload

To simply submit the configure/build/test results on CDash skipping the upload part, building target Experimental is sufficient. This is expected to work only for Slicer >= 4.1.2. See issue #2166

$ cd SlicerExtensionsCustomIndex-build
$ cd foo-build
$ make Experimental

Extensions build, test, package and upload using Slicer_UPLOAD_EXTENSIONS option

$ cd SlicerExtensionsCustomIndex-build
$ cmake -DSlicer_DIR:PATH=/path/to/Slicer-master-SuperBuild-Release/Slicer-build \
 -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsCustomIndex \
 -DCMAKE_BUILD_TYPE:STRING=Release \
 -DSlicer_UPLOAD_EXTENSIONS:BOOL=ON \
 -DMIDAS_PACKAGE_URL:STRING=http://slicer.kitware.com/midas3 \
 -DMIDAS_PACKAGE_EMAIL:STRING=jchris.fillionr@kitware.com \
 -DMIDAS_PACKAGE_API_KEY:STRING=a0b012c0123d012abc01234a012345a0 \
 /path/to/Slicer-master/Extensions/CMake

Build your own set of extensions against Slicer 4.1.1 build tree

Considering the following assumptions:

1. Folder SlicerExtensionsCustomIndex contains the extension description files of your choice
2. Slicer 4.1.1 has been checkout into /path/to/Slicer-411 and built into /path/to/Slicer-411-SuperBuild-Release
3. To upload extension(s) on the extensions server, an API key has been obtained.

The associated extensions could be built following the instruction listed in the previous section and changing occurences of Slicer-master into Slicer-411.

Build slicer extensions associated with Slicer trunk

Considering the following assumption:

1. Slicer trunk has been checkout into /path/to/Slicer-master and built into /path/to/Slicer-master-SuperBuild-Release

The associated extensions could be built doing:

$ git clone git://github.com/Slicer/ExtensionsIndex.git SlicerExtensionsIndex-master
$ mkdir SlicerExtensionsIndex-master-build
$ cd SlicerExtensionsIndex-master-build
$ cmake -DSlicer_DIR:PATH=/path/to/Slicer-master-SuperBuild-Release/Slicer-build \
 -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsIndex-master \
 -DCMAKE_BUILD_TYPE:STRING=Release \
 /path/to/Slicer-master/Extensions/CMake
$ make

Build slicer extensions associated with Slicer 4.1.1

Considering the following assumption:

1. Slicer trunk has been checkout into /path/to/Slicer-411 and built into /path/to/Slicer-411-SuperBuild-Release

The associated extensions could be built doing:

$ git clone git://github.com/Slicer/ExtensionsIndex.git -b 4.1.1 SlicerExtensionsIndex-411
$ mkdir SlicerExtensionsIndex-411-build
$ cd SlicerExtensionsIndex-411-build
$ cmake -DSlicer_DIR:PATH=/path/to/Slicer-411-SuperBuild-Release/Slicer-build \
 -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsIndex-411 \
 -DCMAKE_BUILD_TYPE:STRING=Release \
 /path/to/Slicer-411/Extensions/CMake
$ make

Dashboard driven build

Continuous and nightly extension dashboards are setup on the slicer factory machine maintained by Kitware folks. Assuming you install your own extensions server, you could also distribute your own set of extensions.

• Setting both nightly and continuous builds of the extensions is a key component of the Slicer continuous integration process.

• By customizing the extension template dashboard script, it is possible to easily setup dashboard client submitting to CDash.

• The images reported below illustrate the dashboard submissions associated with the continuous and nightly builds of Slicer extensions associated to both Slicer trunk and Slicer 4.1.1.

Extension description file

See https://github.com/Slicer/ExtensionsIndex/wiki/Extension-description-file

Extension

A extension bundles one or multiple slicer modules.

Extensions Catalog

• The extensions catalog provides Slicer users with a convenient web site allowing to browse, download and install available extensions:

• from within Slicer with the help of the extensions manager

• from the web: http://slicer.kitware.com/midas3/slicerappstore

Extensions server

• An extensions server is a MIDAS instance having the plugins slicerpackages and slicerappstore installed.

• Assuming you install your own extensions server, it is possible to manage, serve and distribute extensions yourself. As depicted on the image below, Slicer users will have to set a different extensions server in Edit -> Application Settings -> Extensions.

• The authoritative slicer extensions server is http://slicer.kitware.com/midas3

Setting up an account and obtaining an API key

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

1. Create an account by registering

2. Join the NA-MIC community

3. Send an email on the slicer developers list presenting your extension(s) and asking to be granted write permission on the experimental folder.

4. Then, you should be able to retrieve your API key looking at your account details. Note that any one of the API key associated with a given user account is valid. It's the user role to manage its keys.

Install your own extensions server

To understand what are the steps required to install and manage your own extensions server, consider reading MIDAS server installation instructions.

Make also sure to install and configure the plugins slicerpackages and slicerappstore.

Meta

• Code: git clone git://github.com/Slicer/ExtensionsIndex.git
• Bugs: http://github.com/Slicer/ExtensionsIndex/issues

License

• 3D Slicer license