Difference between revisions of "Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions"

From Slicer Wiki
Jump to: navigation, search
(32 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
<noinclude>{{documentation/versioncheck}}</noinclude>
 
<noinclude>{{documentation/versioncheck}}</noinclude>
−
== Step-by-step: How to create, publish and distribute an extension ? ==
 
  
−
<ol start="1" style="list-style-type: decimal;">
+
{{TOC right}}
  
−
<li><p>Scan through the [[Documentation/{{documentation/version}}/FAQ/Extensions|user]] and [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions|developer]] extension FAQs</p></li>
+
To learn what is an extension, see [[Documentation/Nightly/Developers/FAQ#What_is_an_extension_.3F|here]]
  
−
<li><p>(Optionally) Present your extension(s) on the [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel slicer developers list] to check if other developer are working on a similar project, to seek for advice or to reach out for potential collaborator.</p></li>
+
== Step-by-step: How to create, publish, distribute and maintain an extension ? ==
  
−
<li><p>[[Documentation/{{documentation/version}}/Developers/Build_Instructions|Build Slicer application]] in <code>Release</code></p></li>
+
* Scan through the [[Documentation/{{documentation/version}}/FAQ/Extensions|user]] and [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions|developer]] extension FAQs
 +
* Inform a community about your plans on the [https://discourse.slicer.org Slicer forum] to get information about potential parallel efforts (other developers may already work on a similar idea and you could join or build on each other's work), past efforts (related tools might have been available in earlier Slicer versions or in other software that you may reuse), and get early feedback from prospective users. You may also seek advice on the name of your extension and how to organize features into modules. All these can save you a lot of time in the long term.
 +
* Optional (required if developing loadable or CLI [[Documentation/{{documentation/version}}/Developers/Modules|module types]]): [[Documentation/{{documentation/version}}/Developers/Build_Instructions|Build Slicer application]] in <code>Release</code>. Not needed if you only develop Python modules.
 +
* Use the Extension Wizard module in Slicer to create an extension that will contain your module(s). Learn more about ExtensionWizard capabilities [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|here]]. To learn about extension description file format see [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|here]]
 +
* Upload source code of your extension to a publicly available repository. It is recommended to start the repository name with "Slicer" (to make Slicer extensions easier to identify) followed by your extension name (for example, "Sequences" extension is stored in "SlicerSequences" repository). However, this is not a mandatory requirement. If you have a compelling reason not to use Slicer prefix, please make a note while making the pull request.
 +
** GitHub is recommended (due to large user community, free public project hosting): join [https://github.com/join Github] and [https://help.github.com/articles/set-up-git#set-up-git setup Git]
 +
** Extension Wizard command-line interface can upload source code of your extension to GitHub:
 +
{{pre2|<nowiki>$ bin/slicerExtensionWizard --publish ~/Slicer-MyExtension/</nowiki>}}
 +
* Implement your extension. <code>Hack, hack, hack :)</code>.
 +
* Create documentation page for your extension
 +
** It is recommended to put documentation in a README.md file in your repository use the Slicer wiki: [[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension#Extension_page|Create a documentation page for your extension]].
 +
* Optional (only needed, if you want to upload test data to MIDAS or troubleshoot extension upload problems): [[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|Create an account on the extension server and obtain an API Key]]. You will then use your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples. Go to [http://slicer.kitware.com/midas3/community/23 NA-MIC community] and click on <code>Join community</code></p></li>
 +
* Optional (required for loadable and CLI modules): [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions#How_to_build_an_extension_.3F|Build your extension]]
 +
* Test your extension:
 +
** If you have built your extension then build the PACKAGE target to create a package file that you can install from the Extension Manager by clicking the small tool icon in the top-right corner.
 +
** If you have not built your extension then set up your extension manually: [[Documentation/{{documentation/version}}/Developers/FAQ#How_to_manually_install_an_extension.3F|Build your extension]]
 +
* If you consider your extension is ready for distribution, contribute it to the ExtensionsIndex:
 +
** Fork ExtensionIndex repository on GitHub by clicking ''Fork'' button on https://github.com/Slicer/ExtensionsIndex page
 +
** Add your .s4ext file to your forked repository: it can be done using a git client or simply by clicking ''Upload files'' button
 +
** Create a pull request: by clicking ''Create pull request'' button
 +
** Note: the [[Documentation/Nightly/Developers/ExtensionWizard|Extension Wizard]] can automate this by the following command:
  
−
<li><p>Use the Wizard to create an extension bundling one Command line module:</p>
+
  {{pre2|<nowiki>$ bin/slicerExtensionWizard --contribute ~/Slicer-MyExtension/</nowiki>}}
  
−
{|width = "100%"
+
=== Contribution Checklist ===
−
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Linux or MacOSX
 
−
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Windows
 
−
|-
 
−
| valign="top" |
 
−
Start a terminal.
 
−
| valign="top" |
 
−
Start Git Bash (not the Windows command line). [https://help.github.com/articles/set-up-git#platform-windows Need help ?]
 
−
|-
 
−
|colspan="2"|
 
−
{{pre2|<nowiki>
 
−
$ cd Slicer-SuperBuild/Slicer-build
 
  
−
$ bin/slicerExtensionWizard --create MyExtension --addModule cli:MyCLI ~/
+
* Wait for your pull request to be merged. Respond to comments posted on the pull request. The [https://github.com/Slicer/ExtensionsIndex/blob/master/.github/PULL_REQUEST_TEMPLATE.md following checklist] will automatically be associated with your pull request.
−
</nowiki>}}
 
  
−
To learn more about:
+
=== Continuous Integration ===
−
: the Wizard, click [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|here]].
 
−
: the different type of modules, click [[Documentation/{{documentation/version}}/Developers/Modules|here]].
 
  
−
|}
+
If you shared your extension by using the ExtensionWizard, make sure you know about the Slicer testing dashboard:
  
−
</li>
+
<p class="mw-code"> [[{{tool|logo|cdash}}|x25px]] http://slicer.cdash.org/index.php?project=Slicer4&display=project</p>
  
−
<li><p>Create a repository named <code>Slicer-MyExtension</code> to save your extension located in <code>~/MyExtension</code> directory.</p>
+
The dashboard will attempt to check out the source code of your extension, build, test and package it on Linux, MacOSX and Windows platforms.  
−
  <ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;"> 
 
−
    <li>We recommend [https://github.com/ GitHub]. [https://help.github.com/articles/create-a-repo Need help ?]</li>
 
−
    <li>Read our [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions#Should_the_name_of_the_source_repository_match_the_name_of_the_extension_.3F|FAQ]] to learn about repository naming convention.
 
−
  </ol>
 
−
</li>
 
  
−
<li><p>Implement your extension. <code>Hack, hack, hack :)</code>. Make sure to commit often using meaningful commit message.</p></li>
 
  
−
<li><p>[[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension#Extension_page|Create a documentation page for your extension]].</p></li>
+
To find your extension, use the following link replacing <code>Slicer-MyExtension</code> with the name of your extension:
  
−
<li><p>[[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|Create an account on the extension server and obtain an API Key]]. You will then use your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples.</p></li>
+
<pre>
 +
http://slicer.cdash.org/index.php?project=Slicer4&filtercount=1&showfilters=1&field1=buildname&compare1=63&value1=Slicer-MyExtension
 +
</pre>
  
−
<li><p>If not already done, go to [http://slicer.kitware.com/midas3/community/23 NA-MIC community] and click on <code>Join community</code></p></li>
+
For example, here is the link to check the status of the <code>SlicerDMRI</code> extension:
  
−
<li>{{:Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions/ExperimentalFolderAccess}}</li>
+
<p class="mw-code">http://slicer.cdash.org/index.php?project=Slicer4&filtercount=1&showfilters=1&field1=buildname&compare1=63&value1=SlicerDMRI</p>
  
−
<li><p>Assuming the source code of your extension is located in folder <code>MyExtension</code>, you could upload your extension doing:
+
If you see red in any of the columns for your extension, click on the hyperlinked number of errors to see the details.
  
−
{|width = "100%"
+
Always check the dashboard after you first introduce your extension, or after you make any changes to the code!
−
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Linux or MacOSX (Makefile)
 
−
! width="50%" style="border-bottom: 1px solid darkgrey;font-size: 75%;"| Windows (Visual Studio)
 
−
|-
 
−
| valign="top" |
 
−
{{pre2|<nowiki>
 
−
$ mkdir MyExtension-build
 
−
 
 
−
$ cd MyExtension-build
 
−
 
 
−
$ cmake -DCMAKE_BUILD_TYPE:STRING=Release -DMIDAS_PACKAGE_EMAIL:STRING=<YOUR-MIDAS-LOGIN> -DMIDAS_PACKAGE_API_KEY:STRING=<YOUR-MIDAS-APIKEY> -DSlicer_DIR:PATH=/path/to/Slicer-Superbuild/Slicer-build ../MyExtension
 
−
 
 
−
$ make ExperimentalUpload
 
−
</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>, <code>MIDAS_PACKAGE_EMAIL</code> and <code>MIDAS_PACKAGE_API_KEY</code> entries to the cache</li>
 
−
[[File:Slicer Extensions Configure Windows.png|600px]]
 
−
<li>Click on <code>Configure</code>, select Generator, then click on <code>Generate</code> button.</li>
 
−
<li>Open <code>MyExtension.sln</code> (1), select <code>Release</code> configuration (2), select <code>ExperimentalUpload</code> (3) and <code>Build</code> (4).</li>
 
−
[[File:Slicer_Extension_ExperimentalUpload_Windows_VS2008.png|400px]]
 
−
</ol>
 
−
|}
 
−
</p></li>
 
−
 
 
−
<li><p>Check submission results on the dashboard: http://slicer.cdash.org/index.php?project=Slicer4#Extensions-Experimental</p>
 
−
  <ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
 
−
  <li>You should expect the test <code>MyCLITest</code> to fail with error of the form:
 
−
  {{pre2|scroll|[nrrd] nrrdIoStateDataFileIterNext: couldn't open "~/MyExtension-build/MyCLI/Data/Baseline/CLIModuleTemplateTest.raw"}}
 
−
  This is explained by the fact the <code>*.nhdr</code> file available on midas and downloaded locally still reference <code>CLIModuleTemplateTest.raw</code></li>
 
−
  </ol>
 
−
</li>
 
−
 
−
<li><p>Check that the extension can be installed by starting the Slicer executable from <code>/path/to/Slicer-Superbuild/Slicer-build</code> and installing your extension as explained [[Documentation/{{documentation/version}}/SlicerApplication/ExtensionsManager|here]].</p></li>
 
−
 
 
−
<li>
 
−
  <p>If you consider your extension ready for distribution, follow [[Documentation/{{documentation/version}}/Developers/Tutorials/Contribute_Extension_Description_File|these instructions.]] to contribute the already generated description file.</p>
 
−
  <ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;"> 
 
−
    <li>The generated extension description file file is named <code>&lt;MyExtension&gt;.s4ext</code> and is located in the extension build directory <code>~/MyExtension-build</code></li>
 
−
    <li>Details about the extension description file formet are available [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|here]]</li>
 
−
  </ol>
 
−
</li>
 
−
 
 
−
</ol>
 
−
 
 
−
<!--
 
−
<noinclude>
 
−
{{:Documentation/{{documentation/version}}/Developers/FAQ/Extensions|Extensions}}
 
−
</noinclude>
 
−
-->
 

Revision as of 20:05, 7 January 2019

Home < Documentation < Nightly < Developers < Tutorials < BuildTestPackageDistributeExtensions


For the latest Slicer documentation, visit the read-the-docs.


To learn what is an extension, see here

Step-by-step: How to create, publish, distribute and maintain an extension ?

  • Scan through the user and developer extension FAQs
  • Inform a community about your plans on the Slicer forum to get information about potential parallel efforts (other developers may already work on a similar idea and you could join or build on each other's work), past efforts (related tools might have been available in earlier Slicer versions or in other software that you may reuse), and get early feedback from prospective users. You may also seek advice on the name of your extension and how to organize features into modules. All these can save you a lot of time in the long term.
  • Optional (required if developing loadable or CLI module types): Build Slicer application in Release. Not needed if you only develop Python modules.
  • Use the Extension Wizard module in Slicer to create an extension that will contain your module(s). Learn more about ExtensionWizard capabilities here. To learn about extension description file format see here
  • Upload source code of your extension to a publicly available repository. It is recommended to start the repository name with "Slicer" (to make Slicer extensions easier to identify) followed by your extension name (for example, "Sequences" extension is stored in "SlicerSequences" repository). However, this is not a mandatory requirement. If you have a compelling reason not to use Slicer prefix, please make a note while making the pull request.
    • GitHub is recommended (due to large user community, free public project hosting): join Github and setup Git
    • Extension Wizard command-line interface can upload source code of your extension to GitHub:
$ bin/slicerExtensionWizard --publish ~/Slicer-MyExtension/
  • Implement your extension. Hack, hack, hack :).
  • Create documentation page for your extension
  • Optional (only needed, if you want to upload test data to MIDAS or troubleshoot extension upload problems): Create an account on the extension server and obtain an API Key. You will then use your midas login and api key to substitute <YOUR-MIDAS-LOGIN> and <YOUR-MIDAS-APIKEY> in the examples. Go to NA-MIC community and click on Join community

  • Optional (required for loadable and CLI modules): Build your extension
  • Test your extension:
    • If you have built your extension then build the PACKAGE target to create a package file that you can install from the Extension Manager by clicking the small tool icon in the top-right corner.
    • If you have not built your extension then set up your extension manually: Build your extension
  • If you consider your extension is ready for distribution, contribute it to the ExtensionsIndex:
    • Fork ExtensionIndex repository on GitHub by clicking Fork button on https://github.com/Slicer/ExtensionsIndex page
    • Add your .s4ext file to your forked repository: it can be done using a git client or simply by clicking Upload files button
    • Create a pull request: by clicking Create pull request button
    • Note: the Extension Wizard can automate this by the following command:
$ bin/slicerExtensionWizard --contribute ~/Slicer-MyExtension/

Contribution Checklist

  • Wait for your pull request to be merged. Respond to comments posted on the pull request. The following checklist will automatically be associated with your pull request.

Continuous Integration

If you shared your extension by using the ExtensionWizard, make sure you know about the Slicer testing dashboard:

CDash-logo.png http://slicer.cdash.org/index.php?project=Slicer4&display=project

The dashboard will attempt to check out the source code of your extension, build, test and package it on Linux, MacOSX and Windows platforms.


To find your extension, use the following link replacing Slicer-MyExtension with the name of your extension: 

http://slicer.cdash.org/index.php?project=Slicer4&filtercount=1&showfilters=1&field1=buildname&compare1=63&value1=Slicer-MyExtension

For example, here is the link to check the status of the SlicerDMRI extension:

http://slicer.cdash.org/index.php?project=Slicer4&filtercount=1&showfilters=1&field1=buildname&compare1=63&value1=SlicerDMRI

If you see red in any of the columns for your extension, click on the hyperlinked number of errors to see the details.

Always check the dashboard after you first introduce your extension, or after you make any changes to the code!

Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions&oldid=60686"