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

From Slicer Wiki
Jump to: navigation, search
Line 2: Line 2:
  
 
To learn what is an extension, see [[Documentation/Nightly/Developers/FAQ#What_is_an_extension_.3F|here]]
 
To learn what is an extension, see [[Documentation/Nightly/Developers/FAQ#What_is_an_extension_.3F|here]]
−
 
−
== Conventions ==
 
−
 
−
* Terminal command - Block like the one below indicates that the command should be executed in a terminal.
 
−
 
−
<ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;"> 
 
−
<li>On '''Windows''', Git Bash is expected (not the Windows command line). [https://help.github.com/articles/set-up-git#platform-windows Need help ?]</li>
 
−
</ol>
 
−
 
−
{{pre2|<nowiki>$ echo "This is a command"</nowiki>}}
 
−
 
  
 
== Step-by-step: How to create, publish and distribute an extension ? ==
 
== Step-by-step: How to create, publish and distribute an extension ? ==
  
−
<ol start="1" style="list-style-type: decimal;">
+
* Scan through the [[Documentation/{{documentation/version}}/FAQ/Extensions|user]] and [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions|developer]] extension FAQs
−
 
+
* Optional: 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.
−
<li><p>Scan through the [[Documentation/{{documentation/version}}/FAQ/Extensions|user]] and [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions|developer]] extension FAQs</p></li>
+
* 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>.
−
 
+
* Use the Extension Wizard to create an extension bundling 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]]
−
<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>
+
* Upload source code of your extension to a publicly available repository
−
 
+
** 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]
−
<li><p>[[Documentation/{{documentation/version}}/Developers/Build_Instructions|Build Slicer application]] in <code>Release</code></p></li>
+
** Extension Wizard command-line interface can upload source code of your extension to GitHub:
−
 
 
−
<li><p>Use the Wizard to create an extension bundling one Command line module:</p>
 
−
 
 
−
{{pre2|<nowiki>
 
−
$ cd Slicer-SuperBuild/Slicer-build
 
−
 
 
−
$ bin/slicerExtensionWizard --create Slicer-MyExtension --addModule cli:MyCLI ~
 
−
</nowiki>}}
 
−
 
 
−
<ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;"> 
 
−
  <li>By specifying <code>~</code> as destination, the extension will be created into your home directory.</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 extension naming convention.
 
−
</ol>
 
−
 
 
−
To learn more about:
 
−
: the ExtensionWizard capabilities, click [[Documentation/{{documentation/version}}/Developers/ExtensionWizard|here]].
 
−
: the different type of modules, click [[Documentation/{{documentation/version}}/Developers/Modules|here]].
 
−
 
 
−
</li>
 
−
 
 
−
<li><p>If not already done, join [https://github.com/join Github] and [https://help.github.com/articles/set-up-git#set-up-git setup Git]</p></li>
 
−
 
 
−
<li><p>Save the source code of your extension by publishing it on Github</p>
 
−
 
 
 
{{pre2|<nowiki>$ bin/slicerExtensionWizard --publish ~/Slicer-MyExtension/</nowiki>}}
 
{{pre2|<nowiki>$ bin/slicerExtensionWizard --publish ~/Slicer-MyExtension/</nowiki>}}
−
 
+
* Implement your extension. <code>Hack, hack, hack :)</code>.
−
</li>
+
* Create documentation page for your extension
−
 
+
** It is recommended to use the Slicer wiki: [[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension#Extension_page|Create a documentation page for your extension]].
−
<li><p>Implement your extension. <code>Hack, hack, hack :)</code>. Make sure to commit often using meaningful commit message.</p></li>
+
* Optional (necessary, 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]]
−
<li><p>[[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension#Extension_page|Create a documentation page for your extension]].</p></li>
+
* 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.
−
<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>
+
** 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:
−
<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>
+
** Fork ExtensionIndex repository (https://github.com/Slicer/ExtensionsIndex), add your extension, and send a pull request
−
 
+
** The Extension Wizard can automate this by the following command:
−
<li>Use of the experimental upload feature is optional:  {{:Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions/ExperimentalFolderAccess}}</li>
 
−
 
 
−
<li><p>Assuming the source code of your extension is located in folder <code>MyExtension</code>, you could upload your extension doing:
 
−
 
 
−
<ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;">
 
−
  <li>To avoid typing the API email and key, you can set the environment variables <code>MIDAS_PACKAGE_EMAIL</code> and  <code>MIDAS_PACKAGE_API_KEY</code>. More details [[Documentation/{{documentation/version}}/Developers/FAQ#How_to_cache_API_credentials_.3F|here]]</li>
 
−
</ol>
 
−
 
 
−
{|width = "100%"
 
−
! 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>}}
 
−
 
 
−
'''MaxOSX''': Extension '''must be configured''' specifying <code>CMAKE_OSX_*</code> variables matching the one used to configure Slicer:
 
−
* <code>-DCMAKE_OSX_ARCHITECTURES:STRING=x86_64</code>
 
−
* <code>-DCMAKE_OSX_DEPLOYMENT_TARGET:STRING=/same/as/Slicer</code>
 
−
* <code>-DCMAKE_OSX_SYSROOT:PATH=SameAsSlicer</code>
 
−
 
 
−
| 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 is ready for distribution, contribute it to the ExtensionsIndex:</p>
 
  
 
   {{pre2|<nowiki>$ bin/slicerExtensionWizard --contribute ~/Slicer-MyExtension/</nowiki>}}
 
   {{pre2|<nowiki>$ bin/slicerExtensionWizard --contribute ~/Slicer-MyExtension/</nowiki>}}
−
 
−
  <ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;"> 
 
−
    <li>To contribute an extensions build against Slicer {{Documentation/currentversion}}. See [[Documentation/{{documentation/version}}/Developers/Tutorials/Contribute_Extension_Description_File_using_Extension_Wizard|here]].</li>
 
−
    <li>To learn about extension description file format. See [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|here]]</li>
 
−
  </ol>
 
−
 
−
</li>
 
−
 
−
</ol>
 

Revision as of 03:19, 7 November 2016

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 and distribute an extension ?

  • Scan through the user and developer extension FAQs
  • Optional: Present your extension(s) on the 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.
  • Optional (required if developing loadable or CLI module types): Build Slicer application in Release.
  • Use the Extension Wizard to create an extension bundling 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
    • 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 (necessary, 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: 
$ bin/slicerExtensionWizard --contribute ~/Slicer-MyExtension/
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions&oldid=47413"