Documentation/Nightly/Developers/FAQ/Extensions
For the latest Slicer documentation, visit the read-the-docs. |
Contents
- 1 Extensions
- 1.1 What is the Extensions Index ?
- 1.2 What is an API Key ?
- 1.3 How to obtain an API key to submit on the extension server ?
- 1.4 Where can I find the extension templates ?
- 1.5 How to build an extension ?
- 1.6 How to package an extension ?
- 1.7 How to upload an extension ?
- 1.8 What are the extension specific targets: ExperimentalUpload, ExperimentalUploadOnly, ... ?
- 1.9 Is --launch flag available for a MacOSX installed Slicer.app ?
- 1.10 What is the difference between Documentation/Nightly/Modules and Documentation/Nightly/Extensions ?
- 1.11 Which URL should be associated with EXTENSION_HOMEPAGE metadata ?
- 1.12 How to rename an extension to add new features ?
Extensions
What is the 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 ?
In order to upload extensions on the slicer extensions server, it is required to:
Create an account on the extension server: http://slicer.kitware.com by clicking on the
Register
link in the top right cornerGo to NA-MIC community and click on
Join community
Retrieve your API key looking at your account details:
- Go to http://slicer.kitware.com. If needed, signin by clicking on
Login
in the top right corner. - Click on your name in the top right corner.
- Click on
My account
. - Click on
API
tab. Copy the
API Key
associated withDefault
application.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 namedDefault
.
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.
- Go to http://slicer.kitware.com. If needed, signin by clicking on
This image shows the top portion of http://slicer.kitware.com after it has been expanded by clicking the Register
button.
Where can I find the extension templates ?
The extensions templates are available in the Slicer source tree: https://github.com/Slicer/Slicer/tree/master/Extensions/Testing/
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 |
|
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 |
|
How to upload an extension ?
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 |
|
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:
- Fixup of Slicer application itself. See SlicerCPack.cmake#L36-68 and SlicerCPackBundleFixup.cmake.in
- 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