View source for Documentation/4.3/Developers/FAQ/Extensions

<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 extensions templates are available in the Slicer source tree: https://github.com/Slicer/Slicer/tree/master/Extensions/Testing/

Using the [[Documentation/{{documentation/version}}/Developers/ModuleWizard|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 ? ==

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.