|
Tags: 2017 source edit, Replaced |
| (74 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 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>.
| + | | 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
| |
| − | * 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.
| |
| − | | |
| − | == 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:
| |
| − | <pre>
| |
| − | <ExtensionName>_BUILD_SLICER_EXTENSION
| |
| − | </pre>
| |
| − | | |
| − | 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
| |
