|
Tags: 2017 source edit, Replaced |
(79 intermediate revisions by 10 users not shown) |
Line 1: |
Line 1: |
| <noinclude>{{documentation/versioncheck}}</noinclude> | | <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 ? ==
| + | {{documentation/banner |
− | | + | | text = [https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html#frequently-asked-questions This page has been moved to read-the-docs.] |
− | Assuming your extension is named <code>AwesomeFilter</code>, generally, we recommend to name the extension repository either <code>Slicer-AwesomeFilter<code>, <code>SlicerAwesomeFilter<code> or <code>Slicer_AwesomeFilter<code>.
| + | | background-color = 8FBC8F }} |
− | | |
− | 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
| |