|
|
| Line 1: |
Line 1: |
| − | <!--
| + | == Step-by-step: How to create, publish and distribute an extension ? == |
| − | The process of creating an extension is as follows:
| |
| − | * Create a module (command line, scripted or loadable)
| |
| − | * Make sure that it compiles on all supported platforms
| |
| − | * Create an s3ext file pointing to the source code
| |
| − | * Talk to the slicer team to integrate it into the nightly build process.
| |
| − | -->
| |
| − | | |
| − | == What is an extension ? ==
| |
| − | {{:Documentation/{{documentation/version}}/Extensions/Description}}
| |
| − | | |
| − | | |
| − | | |
| − | = Prerequisites =
| |
| − | == Create an extension using the Wizard ==
| |
| − | * Create an extension using the [[Documentation/{{documentation/version}}/Developers/ModuleWizard|Wizard]]
| |
| − | == Upload an extension in the experimental folder == | |
| − | * [https://github.com/Slicer/ExtensionsIndex#extension-build-test-package-and-upload-using-experimentalupload-target Upload an extension in the experimental folder]
| |
| − | | |
| − | = Contributing a new extension =
| |
| − | | |
| − | == Extensions build against Slicer trunk ==
| |
| − | | |
| − | The following instruction describes how to contribute extension description file for an extension being built against slicer trunk.
| |
| − | | |
| − | <ol start="1" style="list-style-type: decimal;">
| |
| − | | |
| − | <li><p>Fork the <code>ExtensionsIndex</code>: http://github.com/Slicer/ExtensionsIndex. Click [http://help.github.com/forking/ here] for forking instructions.</p></li>
| |
| − | | |
| − | <li><p>Clone your fork, then create a topic named <code>add-<ExtensionName></code></p></li>
| |
| − | <pre>
| |
| − | git clone git@github.com:USER/ExtensionsIndex SlicerExtensionsIndex
| |
| − | cd SlicerExtensionsIndex
| |
| − | git checkout -b add-YourExtensionName
| |
| − | </pre>
| |
| − | | |
| − | <li><p>Commit your description file. Commit title should be <code>Add YourExtensionName extension</code> and the content should provide details about the extension.</p></li>
| |
| − | <li><p>Push the topic to your fork</p></li>
| |
| − | <pre>
| |
| − | git push origin
| |
| − | </pre>
| |
| − | <li><p>On your github fork, click on "Pull Request". Slicer folks will be automatically notified.</p></li>
| |
| − | <li><p>That's it !</p></li>
| |
| − | | |
| − | </ol>
| |
| − | | |
| − | | |
| − | | |
| − | | |
| − | | |
| − | * [https://github.com/Slicer/ExtensionsIndex#contributing See instructions on github]
| |
| − | * Consider also reading [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|Extension description file format]]
| |
| − | | |
| − | == Extensions build against Slicer {{Documentation/currentversion}} ==
| |
| − | | |
| − | * Follow instruction reported in section [[Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions#Extensions_build_against_Slicer_{{Documentation/currentversion}}_2|Requesting an extension version update / Extensions_build_against_Slicer_{{Documentation/currentversion}}]] and set the title of the commit to be <code>add-<ExtensionName></code>.
| |
| − | | |
| − | = Requesting an extension update =
| |
| − | | |
| − | On your local fork, the idea is to create the following topic branches:
| |
| − | * <code>update-<YourExtensionName></code> based of [https://github.com/Slicer/ExtensionsIndex/tree/master <code>master</code>] integration branch.
| |
| − | * <code>update-<YourExtensionName>-4.2</code> based of [https://github.com/Slicer/ExtensionsIndex/tree/4.2 <code>4.2</code>] integration branch.
| |
| − | | |
| − | | |
| − | == Extensions build against Slicer trunk ==
| |
| − | | |
| − | The following instruction describes how to contribute extension description file updates for an extension being built against slicer trunk.
| |
| | | | |
| | <ol start="1" style="list-style-type: decimal;"> | | <ol start="1" style="list-style-type: decimal;"> |
| | | | |
| − | <li><p>Update the <code>master</code> branch of both your local clone and your online <code>ExtensionsIndex</code> fork</p></li> | + | <li><p>Scan through the [[Documentation/{{documentation/version}}/FAQ/Extensions|user]] and [[Documentation/{{documentation/version}}/Developers/FAQ/Extensions|developer]] extension FAQs</p></li> |
| − | <pre>
| |
| − | git remote add upstream git://github.com/Slicer/ExtensionsIndex # Add reference to the authoritative ExtensionsIndex
| |
| − | git fetch upstream # Fetch change of the authoritative ExtensionsIndex
| |
| − | git checkout master # Checkout master
| |
| − | git reset --hard upstream/master # Reset your local master branch using the authoritative master
| |
| − | git push origin master # Update the master branch of your online fork
| |
| − | </pre> | |
| | | | |
| − | <li><p>If needed, create branch named <code>update-YourExtensionName</code></p></li> | + | <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 collaboration.</p></li> |
| − | <pre>
| |
| − | git checkout -b update-YourExtensionName # Create branch update-YourExtensionName
| |
| − | </pre>
| |
| | | | |
| − | <li><p>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</p></li> | + | <li><p>[[Documentation/{{documentation/version}}/Developers/Build_Instructions|Build Slicer application]]</p></li> |
| − | * See https://github.com/Slicer/ExtensionsIndex#build-your-own-set-of-extensions-against-slicer-trunk-build-tree
| |
| − | * If the svn server needs a username and a password, edit the newly generated <code>YourExtensionName.s4ext</code> file to add this information
| |
| − | <li><p>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository (provide a meaningful commit comment)</p></li>
| |
| − | <li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
| |
| − | <pre>
| |
| − | git push origin update-YourExtensionName # Publish the updated branch on your fork
| |
| − | </pre>
| |
| | | | |
| − | <li><p>Create a pull request:</p></li> | + | <li><p>[[Documentation/{{documentation/version}}/Developers/ModuleWizard|Use the Wizard to easily create an extension]] containing one or more Slicer modules.</p></li> |
| − | * Visiting your fork on http://github.com/USER/ExtensionsIndex and, if available, clicking on the <code>Pull request</code> link as explained [https://help.github.com/articles/creating-a-pull-request here].
| |
| − | or
| |
| − | * Using a link similar to the following: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName</code>
| |
| | | | |
| − | Note: If you are using github for hosting your extension source code, make sure to associated a '''Compare View link'''. This is very helpful to summarize the changes.
| + | <li><p>Create a repository to save your work. We recommend [https://github.com/ GitHub]</p></li> |
| − | <pre> | |
| − | You can build the compare view URL manually with the following format:
| |
| | | | |
| − | https://github.com/USER/REPO/compare/[USER:]GIT-REF…[USER:]GIT-REF
| + | <li><p>Implement your extension. <code>Hack, hack, hack :)</code> and commit often.</p></li> |
| | | | |
| − | USER is your GitHub username, REPO is your GitHub repository, and GIT-REF can be a tag, branch, or commit SHA1.
| + | <li><p>[[Documentation/{{documentation/version}}/Developers/Tutorials/DocumentExtension|Create a documentation page for your extension]].</p></li> |
| − | </pre> | |
| − | Source: http://jbuckley.ca/2011/09/githubs-compare-view/
| |
| | | | |
| − | </ol> | + | <li><p>If not alreadt done, send an email on the [http://massmail.bwh.harvard.edu/mailman/listinfo/slicer-devel slicer developers list] asking to be granted write permission on the [http://slicer.kitware.com/midas3/folder/253 experimental folder].</p></li> |
| | | | |
| − | == Extensions build against Slicer {{Documentation/currentversion}} ==
| + | <li><p>[[#How_to_obtain_an_API_key_to_submit_on_the_extension_server_.3F|Create an account on the extension server and obtain an API Key]]. You can then used your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples.</p></li> |
| | | | |
| − | The following instruction describes how to contribute extension description file updates for an extension being built against slicer trunk.
| + | <li><p>Assuming the source code of your extension is located in folder <code>MyExtension</code>, you could upload your extension doing: |
| | | | |
| − | <ol start="1" style="list-style-type: decimal;"> | + | {{pre2|scroll|<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>}}</p></li> |
| | | | |
| − | <li><p>Update the {{Documentation/currentversion}} branch of both your local clone and your online ExtensionsIndex fork</p></li> | + | <li><p>Check submission results on this page: http://slicer.cdash.org/index.php?project=Slicer4#Extensions-Experimental</p></li> |
| − | <pre>
| + | |
| − | git remote add upstream git://github.com/Slicer/ExtensionsIndex # Add reference to the authoritative ExtensionsIndex
| + | <li><p>[[Documentation/{{documentation/version}}/SlicerApplication/ExtensionsManager|Check that the extension can be installed]].</p></li> |
| − | git fetch upstream # Fetch change of the authoritative ExtensionsIndex
| |
| − | git checkout 4.2 # Checkout 4.2
| |
| − | git reset --hard upstream/4.2 # Reset your local 4.2 branch using the authoritative 4.2
| |
| − | git push origin 4.2 # Update the 4.2 branch of your online fork
| |
| − | </pre>
| |
| − | | |
| − | <li><p>If needed, create branch named <code>update-YourExtensionName-4.2</code></p></li>
| |
| − | <pre>
| |
| − | git checkout -b update-YourExtensionName-4.2 # Create branch update-YourExtensionName-4.2
| |
| − | </pre>
| |
| − | | |
| − | | |
| − | <li><p>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</p></li> | |
| − | * See https://github.com/Slicer/ExtensionsIndex#build-your-own-set-of-extensions-against-slicer-trunk-build-tree.
| |
| − | * If the svn server needs a username and a password, edit the newly generated <code>YourExtensionName.s4ext</code> file to add this information.
| |
| − | <li><p>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository providing a meaningful commit comment.</p></li>
| |
| − | <li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
| |
| − | <pre>
| |
| − | git push origin update-YourExtensionName-4.2 # Publish the updated branch on your fork
| |
| − | </pre>
| |
| − | | |
| − | <li><p>Create a pull request:</p></li>
| |
| − | * Visiting your fork on http://github.com/USER/ExtensionsIndex and, if available, clicking on the <code>Pull request</code> link as explained [https://help.github.com/articles/creating-a-pull-request here].
| |
| − | or
| |
| − | * Using a link similar to the following: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName-4.2</code>
| |
| − | | |
| − | Note: If you are using github for hosting your extension source code, make sure to associated a '''Compare View link'''. This is very helpful to summarize the changes.
| |
| − | <pre>
| |
| − | You can build the compare view URL manually with the following format:
| |
| − | | |
| − | https://github.com/USER/REPO/compare/[USER:]GIT-REF…[USER:]GIT-REF
| |
| − | | |
| − | USER is your GitHub username, REPO is your GitHub repository, and GIT-REF can be a tag, branch, or commit SHA1.
| |
| − | </pre> | |
| − | Source: http://jbuckley.ca/2011/09/githubs-compare-view/
| |
| | | | |
| | </ol> | | </ol> |
| | | | |
| | <!-- | | <!-- |
| − | = Submitting a pull request =
| + | Documentation/Nightly/Developers/Tutorials/Contribute_Extension_Description_File |
| | | | |
| − | The following gallery illustrates how to submit a pull request from your <code>ExtensionsIndex</code> fork.
| + | <noinclude> |
| − | | + | {{:Documentation/{{documentation/version}}/Developers/FAQ/Extensions|Extensions}} |
| − | To learn more about pull request. Consider reading: https://help.github.com/articles/using-pull-requests
| + | </noinclude> |
| − | | |
| − | <gallery widths=800px heights=300px perrow=1>
| |
| − | File:Extensions-4.2-pull-request-step1.png|1. Create Pull Request
| |
| − | File:Extensions-4.2-pull-request-step2.png|2. Select base
| |
| − | File:Extensions-4.2-pull-request-step3.png|3. Send Pull Request
| |
| − | File:Extensions-4.2-pull-request-step4.png|4. Verify
| |
| − | </gallery> | |
| | --> | | --> |
| − |
| |
| − | {{:Documentation/{{documentation/version}}/Developers/FAQ/Extensions|Extensions}}
| |
