Difference between revisions of "Documentation/Nightly/Developers/Build ExtensionsIndex"

From Slicer Wiki
Jump to: navigation, search
(moved to readthedocs)
Tags: 2017 source edit, Replaced
 
(8 intermediate revisions by 3 users not shown)
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, 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>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 SlicerExtensionsCustomIndex
 
foo.s4ext
 
bar.s4ext
 
$ mkdir SlicerExtensionsCustomIndex-build
 
$ 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 \
 
/path/to/Slicer-master/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](#extension-build-test-package-and-upload-using-experimentalupload-target)
 
# [Configure (or re-configure) the project passing the options `Slicer_UPLOAD_EXTENSIONS`,
 
`MIDAS_PACKAGE_URL`, `MIDAS_PACKAGE_EMAIL` and `MIDAS_PACKAGE_API_KEY`](#extensions-build-test-package-and-upload-using-slicer_upload_extensions-option)
 
 
 
 
 
==== Extension build, test, package and upload using `ExperimentalUpload` target ====
 
 
 
<pre>
 
$ cd SlicerExtensionsCustomIndex-build
 
$ cd foo-build
 
$ cmake -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 [#2166](http://www.na-mic.org/Bug/view.php?id=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 \
 
-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 4.1.1 build tree ===
 
 
 
Prerequisites:
 
 
 
# Folder <code>SlicerExtensionsCustomIndex</code> contains the [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|extension description files]] of your choice
 
# Slicer 4.1.1 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 4.1.1 ===
 
 
 
Considering the following assumption:
 
 
 
# Slicer trunk has been checkout into `/path/to/Slicer-411` and built into `/path/to/Slicer-411-SuperBuild-Release`
 
 
 
The associated extensions could be built doing:
 
 
 
<pre>
 
$ git clone git://github.com/Slicer/ExtensionsIndex.git -b 4.1.1 SlicerExtensionsIndex-411
 
$ mkdir SlicerExtensionsIndex-411-build
 
$ cd SlicerExtensionsIndex-411-build
 
$ cmake -DSlicer_DIR:PATH=/path/to/Slicer-411-SuperBuild-Release/Slicer-build \
 
-DSlicer_EXTENSION_DESCRIPTION_DIR:PATH=/path/to/SlicerExtensionsIndex-411 \
 
-DCMAKE_BUILD_TYPE:STRING=Release \
 
/path/to/Slicer-411/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].
 
 
 
* 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.
 
 
 
-->
 

Latest revision as of 20:18, 28 September 2021

Home < Documentation < Nightly < Developers < Build ExtensionsIndex