|
Tags: 2017 source edit, Replaced |
| (55 intermediate revisions by 9 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>
| |
| | | | |
| − | == What is an extension description file ? ==
| + | {{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.] |
| − | See [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|Description file description]]
| + | | background-color = 8FBC8F }} |
| − | | |
| − | == Can an extension contain different type of modules ? ==
| |
| − | | |
| − | Yes. Extensions are used to package together all type of Slicer modules.
| |
| − | | |
| − | See also [[Documentation/{{documentation/version}}/Developers/FAQ#What_is_an_extension_.3F|What_is_an_extension ?]]
| |
| − | | |
| − | == 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}}
| |
| − | | |
| − | == How to cache MIDAS credentials ? ==
| |
| − | | |
| − | There is now a new feature that allow you to "cache" your credential [1]. If you set the two environment variables, <code>MIDAS_PACKAGE_EMAIL</code> and <code>MIDAS_PACKAGE_API_KEY</code>, you would simply need to configure your extension using:
| |
| − | | |
| − | {{pre2|
| |
| − | cd MyExtension-build
| |
| − | cmake -DCMAKE_BUILD_TYPE:STRING=Release -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension
| |
| − | make ExperimentalUpload
| |
| − | }}
| |
| − | | |
| − | [1] http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22457
| |
| − | | |
| − | == Where can I find the extension templates ? ==
| |
| − | | |
| − | The module and extension templates are available in the Slicer source tree: https://github.com/Slicer/Slicer/tree/master/Utilities/Templates/
| |
| − | | |
| − | Using the [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|Extension 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 ? ==
| |
| − | | |
| − | <ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
| |
| − | <li>{{:Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions/ExperimentalFolderAccess}}</li>
| |
| − | </ol>
| |
| − | | |
| − | 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>
| |
| − | |}
| |
| − | | |
| − | == Can an extension depend on other extensions ? ==
| |
| − | | |
| − | Yes. An <code>ExtensionFoo</code> can depend on <code>ExtensionBar</code>
| |
| − | | |
| − | The dependency should be specified as a list by setting the variable <code>EXTENSION_DEPENDS</code> in the extension <code>CMakeLists.txt</code>.
| |
| − | | |
| − | For example, if you have <code>ModuleA</code>, <code>ModuleB</code> and <code>ModuleC</code> and <code>ModuleA</code> can be used as standalone one. You could create the following extensions:
| |
| − | | |
| − | * <code>Extension1</code> containing <code>ModuleA</code>
| |
| − | * <code>Extension2</code> containing <code>ModuleB</code> and <code>ModuleC</code>
| |
| − | | |
| − | and add the following variable to <code>Extension2/CMakeLists.txt</code>:
| |
| − | <pre>
| |
| − | set(EXTENSION_DEPENDS Extension1)
| |
| − | </pre>
| |
| − | | |
| − | '''User''':
| |
| − | * If user installs <code>Extension2</code>, <code>Extension1</code> will automatically be installed first.
| |
| − | | |
| − | '''Developer''':
| |
| − | * The generated extension description file have a <code>depends</code> field. See [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|here]] for details.
| |
| − | * The extension framework will build the extension in order. When building <code>Extension2</code>, it will pass the CMake option <code>-DExtension1_DIR:PATH=/path/to/Extension1-build</code>.
| |
| − | | |
| − | == 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
| |
| − | | |
| − | == How often extensions are uploaded on the extensions server ? ==
| |
| − | | |
| − | Slicer extensions are built and uploaded on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]] every day.
| |
| − | | |
| − | To be more specific, the frequency of extensions build and upload associated with:
| |
| − | * Slicer nightly package occurs '''every night''' and also '''continuously''' during the day.
| |
| − | * Slicer {{documentation/currentversion}} lastest stable release package occurs '''every night'''.
| |
| − | | |
| − | == Will an extension be uploaded if associated tests are failing ? ==
| |
| − | | |
| − | Independently of the extension test results, if the extension could be successfully packaged, it will be uploaded on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]].
| |
| − | | |
| − | == How do I associate a remote with my local extension git source directory ? ==
| |
| − | | |
| − | 1) Start a terminal (or Git Bash on Windows)
| |
| − | | |
| − | 2) Get the associated SSH remote url. [https://help.github.com/articles/which-remote-url-should-i-use#cloning-with-ssh Need help ?]
| |
| − | | |
| − | 3) Associate the remote URL with your local git source tree
| |
| − | | |
| − | <pre>
| |
| − | git remote add origin git://github.com/<username>/MyExtension
| |
| − | </pre>
| |
| − | | |
| − | == Which remote name is expected for extension git checkout ? ==
| |
| − | | |
| − | When packaging an extension and generating the associated [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|description file]], the system will look for a remote named <code>origin</code>.
| |
| − | | |
| − | In case you get the error reported below, you will have to either rename or add a remote. [http://git-scm.com/book/en/Git-Basics-Working-with-Remotes Need help ?]
| |
| − | | |
| − | <pre>
| |
| − | CMake Warning at /path/to/Slicer/CMake/FindGit.cmake:144 (message):
| |
| − | No remote origin set for git repository: /path/to/MyExtension
| |
| − | Call Stack (most recent call first):
| |
| − | /path/to/Slicer/CMake/SlicerMacroExtractRepositoryInfo.cmake:99 (GIT_WC_INFO)
| |
| − | /path/to/Slicer/CMake/SlicerExtensionCPack.cmake:55 (SlicerMacroExtractRepositoryInfo)
| |
| − | CMakeLists.txt:25 (include)
| |
| − | </pre>
| |
| − | | |
| − | == Why ExtensionWizard failed to describe extension: "script does not set 'EXTENSION_HOMEPAGE'" ? ==
| |
| − | | |
| − | The issue is that the your extension has a "non standard" layout and the wizard was now way of extracting the expected information.
| |
| − | | |
| − | Similar issue has been discussed and reported for the "SPHARM-PDM" or UKF extension.
| |
| − | | |
| − | First half of the solution would be to move the metadata from Common.cmake to CMakeLists.txt as it is done in [1]
| |
| − | | |
| − | Then, you could make sure there is a project() statement by following what is suggested in [2]
| |
| − | | |
| − | If you prefer not to re-organize your extension, you could still contribute extension description file. See [[Documentation/{{documentation/version}}/Developers/Tutorials/Contribute_Extension_Description_File|here]] for details.
| |
| − | | |
| − | [1] http://www.nitrc.org/plugins/scmsvn/viewcvs.php?view=rev&root=spharm-pdm&revision=228
| |
| − | | |
| − | [2] http://www.na-mic.org/Bug/view.php?id=3737#c12081
| |
