|
Tags: 2017 source edit, Replaced |
| Line 1: |
Line 1: |
| | <noinclude>{{documentation/versioncheck}}</noinclude> | | <noinclude>{{documentation/versioncheck}}</noinclude> |
| − | __TOC__
| |
| | | | |
| − | == Overview ==
| + | {{documentation/banner |
| − | | + | | text = [https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html#extensions-build-system This page has been moved to read-the-docs.] |
| − | This page explain how to build an ExtensionsIndex.
| + | | background-color = 8FBC8F }} |
| − | | |
| − | Think of the ExtensionsIndex as a repository containing a list of [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|extension description files]] (*.s4ext) used by the Slicer extensions build system to build, test, package and upload extensions on an [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]].
| |
| − | | |
| − | Once uploaded on an extensions server, within Slicer, extensions can be installed using the [[Documentation/{{documentation/version}}/SlicerApplication/ExtensionsManager|extensions manager]].
| |
| − | | |
| − | There are two possible approaches to build it:
| |
| − | * [[#Manual_build|Manual build]]
| |
| − | * [[#Dashboard_driven_build|Dashboard driven build]]
| |
| − | | |
| − | == Manual build ==
| |
| − | | |
| − | Locally building an extension index provides a convenient way to:
| |
| − | | |
| − | * check extension description files are valid
| |
| − | * upload one or more extensions at ones to check that Slicer can download and install them
| |
| − | | |
| − | | |
| − | Given a directory containing one or more extension description files, with the help of the extensions build system it is possible to manually
| |
| − | configure and build the associated extensions specifying the following CMake options:
| |
| − | | |
| − | <table class="alternate">
| |
| − | <tr>
| |
| − | <td><code>Slicer_DIR</code></td>
| |
| − | <td>Path to Slicer build tree</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td><code>Slicer_EXTENSION_DESCRIPTION_DIR</code></td>
| |
| − | <td>Path to folder containing extension description files</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | Optionally, it is also possible to specify:
| |
| − | | |
| − | <table class="alternate">
| |
| − | <tr>
| |
| − | <td><code>[http://www.cmake.org/cmake/help/v2.8.8/cmake.html#variable:CMAKE_BUILD_TYPE CMAKE_BUILD_TYPE]</code></td>
| |
| − | <td>On unix-like platform, should match the build type of the associated Slicer build directory</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td><code>CTEST_MODEL</code></td>
| |
| − | <td>By default set to <code>Experimental</code>.<br>Allow to choose on which CDash track results are submitted as well as setting the submission type associated with the uploaded extension.</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td><code>Slicer_UPLOAD_EXTENSIONS</code></td>
| |
| − | <td>By default set to <code>OFF</code>.<br>If enabled, extension builds will be submitted to Slicer dashboard and associated packages will be uploaded to extensions server</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td><code>MIDAS_PACKAGE_URL</code></td>
| |
| − | <td>MIDAS extensions server URL speciManualfying where the extension should be uploaded. For example http://slicer.kitware.com/midas3</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td><code>MIDAS_PACKAGE_EMAIL</code></td>
| |
| − | <td>Email allowing to authenticate to the extensions server.</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td><code>MIDAS_PACKAGE_API_KEY</code></td>
| |
| − | <td>Token allowing to authenticate to the extensions server.</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | | |
| − | The following examples are specific to unix-like platforms and can easily be adapted for windows.
| |
| − | | |
| − | === Build your own set of extensions against Slicer trunk build tree ===
| |
| − | | |
| − | Prerequisites:
| |
| − | | |
| − | # Folder <code>SlicerExtensionsCustomIndex</code> contains the [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|extension description files]] of your choice
| |
| − | # Slicer trunk has been checkout into <code>/path/to/Slicer-master</code> and built into <code>/path/to/Slicer-master-SuperBuild-Release</code>
| |
| − | # To upload extension(s) on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]], an [[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|API key]] has been obtained.
| |
| − | | |
| − | The associated extensions could be built doing:
| |
| − | | |
| − | <pre>
| |
| − | $ ls ExtensionsIndex
| |
| − | foo.s4ext
| |
| − | bar.s4ext
| |
| − | $ mkdir ExtensionsIndex-build
| |
| − | $ cd ExtensionsIndex-build
| |
| − | $ export SLICER=${HOME}/slicer4/latest/Slicer
| |
| − | $ cmake -DSlicer_DIR:PATH=${SLICER}-SuperBuild-Release/Slicer-build \
| |
| − | -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=../ExtensionsIndex \
| |
| − | -DCMAKE_BUILD_TYPE:STRING=Release \
| |
| − | ${SLICER}/Extensions/CMake
| |
| − | $ make
| |
| − | </pre>
| |
| − | | |
| − | Then, to submit the configure/build/test results on [http://slicer.cdash.org/index.php?project=Slicer4#Extensions-Experimental CDash] <code>Extensions-Experimental</code> track
| |
| − | and upload the extension on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]] of your choice,
| |
| − | there are two options:
| |
| − | | |
| − | <!--
| |
| − | # Build the target `ExperimentalUpload` associated with each extensions
| |
| − | -->
| |
| − | # Configure (or re-configure) the project passing the options `Slicer_UPLOAD_EXTENSIONS`, `CTEST_MODEL`,
| |
| − | `MIDAS_PACKAGE_URL`, `MIDAS_PACKAGE_EMAIL` and `MIDAS_PACKAGE_API_KEY`
| |
| − | | |
| − | <!--
| |
| − | ''Note that on Mac you may need to pass in the file paths to git and svn as [http://www.na-mic.org/Bug/view.php?id=4311 described in issue #4311].''
| |
| − | -->
| |
| − | | |
| − | <!--
| |
| − | ==== Extension build, test, package and upload using `ExperimentalUpload` target ====
| |
| − | | |
| − | <pre>
| |
| − | $ cd SlicerExtensionsCustomIndex-build
| |
| − | $ cd foo-build
| |
| − | $ cmake -DCTEST_MODEL:STRING=Experimental -DMIDAS_PACKAGE_URL:STRING=http://slicer.kitware.com/midas3 \
| |
| − | -DMIDAS_PACKAGE_EMAIL:STRING=jchris.fillionr@kitware.com \
| |
| − | -DMIDAS_PACKAGE_API_KEY:STRING=a0b012c0123d012abc01234a012345a0 .
| |
| − | $ make ExperimentalUpload
| |
| − | </pre>
| |
| − | | |
| − | <gallery widths=600px perrow=2>
| |
| − | File:SlicerExtensionsCustomIndex-CDash-Foo-Extension-ExperimentalUpload.png
| |
| − | File:SlicerExtensionsCustomIndex-CDash-foo-download-link.png
| |
| − | </gallery>
| |
| − | | |
| − | To simply submit the configure/build/test results on CDash skipping the upload part, building target `Experimental`
| |
| − | is sufficient. This is expected to work only for Slicer >= 4.1.2. See issue [http://www.na-mic.org/Bug/view.php?id=2166 #2166]
| |
| − | | |
| − | <pre>
| |
| − | $ cd SlicerExtensionsCustomIndex-build
| |
| − | $ cd foo-build
| |
| − | $ make Experimental
| |
| − | </pre>
| |
| − | | |
| − | <gallery widths=600px perrow=2>
| |
| − | File:SlicerExtensionsCustomIndex-CDash-Foo-Extension-Experimental.png
| |
| − | </gallery>
| |
| − | -->
| |
| − | | |
| − | ==== Extensions build, test, package and upload using `Slicer_UPLOAD_EXTENSIONS` option ====
| |
| − | | |
| − | <pre>
| |
| − | $ cd SlicerExtensionsCustomIndex-build
| |
| − | $ cmake -DSlicer_DIR:PATH=/path/to/Slicer-master-SuperBuild-Release/Slicer-build \
| |
| − | -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsCustomIndex \
| |
| − | -DCMAKE_BUILD_TYPE:STRING=Release \
| |
| − | -DCTEST_MODEL:STRING=Experimental \
| |
| − | -DSlicer_UPLOAD_EXTENSIONS:BOOL=ON \
| |
| − | -DMIDAS_PACKAGE_URL:STRING=http://slicer.kitware.com/midas3 \
| |
| − | -DMIDAS_PACKAGE_EMAIL:STRING=jchris.fillionr@kitware.com \
| |
| − | -DMIDAS_PACKAGE_API_KEY:STRING=a0b012c0123d012abc01234a012345a0 \
| |
| − | /path/to/Slicer-master/Extensions/CMake
| |
| − | </pre>
| |
| − | | |
| − | === Build your own set of extensions against Slicer {{Documentation/currentversion}} build tree ===
| |
| − | | |
| − | Prerequisites:
| |
| − | | |
| − | # Folder <code>SlicerExtensionsCustomIndex</code> contains the [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|extension description files]] of your choice
| |
| − | # Slicer {{Documentation/currentversion}} has been checkout into <code>/path/to/Slicer-411</code> and built into <code>/path/to/Slicer-411-SuperBuild-Release</code>
| |
| − | # To upload extension(s) on the [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]], an [[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|API key]] has been obtained.
| |
| − | | |
| − | The associated extensions could be built following the instruction listed in the previous section
| |
| − | and changing occurrences of `Slicer-master` into `Slicer-411`.
| |
| − | | |
| − | === Build slicer extensions associated with Slicer trunk ===
| |
| − | | |
| − | Considering the following assumption:
| |
| − | | |
| − | # Slicer trunk has been checkout into `/path/to/Slicer-master` and built into `/path/to/Slicer-master-SuperBuild-Release`
| |
| − | | |
| − | The associated extensions could be built doing:
| |
| − | | |
| − | <pre>
| |
| − | $ git clone git://github.com/Slicer/ExtensionsIndex.git SlicerExtensionsIndex-master
| |
| − | $ mkdir SlicerExtensionsIndex-master-build
| |
| − | $ cd SlicerExtensionsIndex-master-build
| |
| − | $ cmake -DSlicer_DIR:PATH=/path/to/Slicer-master-SuperBuild-Release/Slicer-build \
| |
| − | -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsIndex-master \
| |
| − | -DCMAKE_BUILD_TYPE:STRING=Release \
| |
| − | /path/to/Slicer-master/Extensions/CMake
| |
| − | $ make
| |
| − | </pre>
| |
| − | | |
| − | === Build slicer extensions associated with Slicer {{Documentation/currentversion}} === | |
| − | | |
| − | Considering the following assumption:
| |
| − | | |
| − | # Slicer trunk has been checkout into `/path/to/Slicer-{{Documentation/currentversion}}` and built into `/path/to/Slicer-{{Documentation/currentversion}}-SuperBuild-Release`
| |
| − | | |
| − | The associated extensions could be built doing:
| |
| − | | |
| − | <pre>
| |
| − | $ git clone git://github.com/Slicer/ExtensionsIndex.git -b 4.3 SlicerExtensionsIndex-4.3
| |
| − | $ mkdir SlicerExtensionsIndex-4.3-build
| |
| − | $ cd SlicerExtensionsIndex-4.3-build
| |
| − | $ cmake -DSlicer_DIR:PATH=/path/to/Slicer-4.3-SuperBuild-Release/Slicer-build \
| |
| − | -DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsIndex-4.3 \
| |
| − | -DCMAKE_BUILD_TYPE:STRING=Release \
| |
| − | /path/to/Slicer-4.3/Extensions/CMake
| |
| − | $ make
| |
| − | </pre>
| |
| − | | |
| − | == Dashboard driven build ==
| |
| − | | |
| − | Continuous and nightly extension dashboards are setup on the slicer factory machine maintained by [http://www.kitware.com Kitware] folks.
| |
| − | | |
| − | Assuming you install your own [[Documentation/{{documentation/version}}/Developers/Extensions/Server|extensions server]], you could also distribute your own set of extensions.
| |
| − | | |
| − | Remarks:
| |
| − | | |
| − | * Setting both nightly and continuous builds of the extensions is a key component of the Slicer continuous integration process.
| |
| − | | |
| − | * By customizing the [https://github.com/Slicer/Slicer/blob/master/Extensions/CMake/SlicerExtensionsDashboardScript.TEMPLATE.cmake extension template dashboard script], it is possible to easily setup dashboard client submitting to [http://slicer.cdash.org/index.php?project=Slicer4 CDash]. See example dashboard scripts that are used on official Slicer build machines [https://github.com/Slicer/DashboardScripts here] (note that these scripts are more complex than the template to allow code reuse between different configurations, but they are tested regularly and so guaranteed to work).
| |
| − | | |
| − | * The images reported below illustrate the dashboard submissions associated with the continuous and nightly builds of Slicer extensions associated to both Slicer trunk and Slicer 4.1.1.
| |
| − | | |
| − | <gallery widths=600px perrow=2>
| |
| − | File:Slicer-411-Extensions-build-system-nightly.png|Extensions-Nightly Slicer 4.1.1
| |
| − | File:Slicer-411-Extensions-build-system-continuous.png|Extensions-Continuous Slicer 4.1.1
| |
| − | File:Slicer-Extensions-build-system-nightly.png|Extensions-Nightly Slicer trunk
| |
| − | File:Slicer-Extensions-build-system-continuous.png|Extensions-Continuous Slicer trunk
| |
| − | </gallery>
| |
| − | | |
| − | | |
| − | <!--
| |
| − | | |
| − | ### Dashboard submissions
| |
| − | | |
| − | Submission of experimental builds are welcome. See [manual build](#manual-build) instructions.
| |
| − | | |
| − | Submission of either continuous or nightly builds of extensions on Slicer [CDash][]
| |
| − | should be done solely by the slicer factory machine maintained by Kitware folks.
| |
| − | While nothing prevent such submission from happening, it won't be possible to upload extensions
| |
| − | on the [extensions server][] without the appropriate credentials.
| |
| − | | |
| − | -->
| |
