UpdateBot: Nightly -> 4.6

2016-11-07T07:37:58Z

Nightly -> 4.6

New page

<noinclude>{{documentation/versioncheck}}</noinclude>
__TOC__

== Overview ==

This page explain how to build an ExtensionsIndex.

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>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](#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 [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 \
-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>

Documentation/4.6/Developers/Build ExtensionsIndex - Revision history

UpdateBot: Nightly -> 4.6