View source for Documentation/4.8/Developers/Build Instructions/Configure

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

== CONFIGURE and generate Slicer solution files ==
There are many ways of customizing Slicer's user interface or feature set. This section describes how a custom Slicer build can be configured at build-time. See an overview of various other options in [http://www.na-mic.org/Wiki/images/b/b0/Slicelets2016.pdf this presentation].

You can configure and generate Slicer solution files using either <code>ccmake</code> or <code>cmake-gui</code>.

<!--
<ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
  <li>While it is not enforced, we strongly recommend you to '''AVOID''' the use of '''SPACES''' for both the <code>source directory</code> and the <code>build directory</code>. We mean it.
  </li>
</ol>
-->
=== Customizing application build ===
Customized editions of Slicer can be generated without changing Slicer source code, just by modifying CMake variables:
* SlicerApp_APPLICATION_NAME: Custom application name to be used, instead of default "Slicer". The name is used in installation package name, window title bar, etc.
* Slicer_DISCLAIMER_AT_STARTUP: String that is displayed to the user after first startup of Slicer after installation (disclaimer, welcome message, etc).
* Slicer_DEFAULT_HOME_MODULE: Module name that is activated automatically on application start.
* Slicer_DEFAULT_FAVORITE_MODULES: Modules that will be added to the toolbar by default for easy access. List contains module names, separated by space character.
* Slicer_CLIMODULES_DISABLED: Built-in CLI modules that will be removed from the application. List contains module names, separated by semicolon character.
* Slicer_QTLOADABLEMODULES_DISABLED: Built-in Qt loadable modules that will be removed from the application. List contains module names, separated by semicolon character.
* Slicer_QTSCRIPTEDMODULES_DISABLED: Built-in scripted loadable modules that will be removed from the application. List contains module names, separated by semicolon character.
* Slicer_USE_PYTHONQT_WITH_OPENSSL: enable/disable building the application with SSL support (ON/OFF)
* Slicer_USE_SimpleITK: enable/disable SimpleITK support (ON/OFF)
* Slicer_BUILD_SimpleFilters: enable/disable building SimpleFilters. Requires SimpleITK. (ON/OFF)
* Slicer_BUILD_EMSegment: enable/disable building EM segmenter (ON/OFF)
* Slicer_USE_PYTHONQT_WITH_TCL: TCL support (ON/OFF)
* Slicer_EXTENSION_SOURCE_DIRS: Defines additional extensions that will be included in the application package as built-in modules. Full paths of extension source directories has to be specified, separated by semicolons.

=== Per-platform instructions===
==== Windows ====
*'''Recommended''': run ''CMake (cmake-gui)'' from the Windows Start menu
** Set the build directory. For example: <code>C:\Slicer-SuperBuild-Debug</code> or <code>C:\Slicer-SuperBuild-Release</code>.
*** Because Windows [http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath doesn't support file path longer than 260 characters] and has a [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2014/016113.html maximum command line length], please make sure that the total path name of your <code>Slicer-build</code> directory is no longer than 50 characters (for example <code>c:\work\Slicer\Slicer-SuperBuild</code> may work). In case of ''any'' build error, use very short directory names: C:\S4 for source directory, C:\S4D for debug build, C:\S4R for release build.
*** You cannot use the same build tree for both release or debug mode builds. If both build types are needed, then the same source directory can be used, but a separate build directory should be created and configured for each build type.
** Select your compiler: Visual Studio 12 2013 Win64
** Configure using default options. You may get a configuration error that <code>QT_QMAKE_EXECUTABLE</code> is not set, which is normal.
** Verify that <code>QT_QMAKE_EXECUTABLE</code> variable is set correctly:
*** CMake may automatically detect an installed version of Qt, but you may want to use a custom built version of Qt (e.g. in Debug mode for use with the designer).
*** Set <code>QT_QMAKE_EXECUTABLE</code> to the path of the <code>qmake.exe</code>, which is inside the <code>bin</code> directory (for example, <code>C:/path/to/qt-everywhere-opensource-build-4.8.6/bin/qmake.exe</code>).
** If building in debug mode: <code>Slicer_USE_SimpleITK</code> option must be turned off to disable building SimpleITK. See more information about why SimpleITK has to be disabled for building in debug mode at http://www.na-mic.org/Bug/view.php?id=3816. You are going to get this build error if you attempt to build in debug mode with SimpleITK enabled: LINK : fatal error LNK1104: cannot open file 'python27_d.lib'
** Click generate then close cmake-gui.
** If building in release mode:
*** Open the top-level Slicer.sln file in the build directory in Visual Studio
*** Set active configuration to Release. Visual Studio will select Debug build configuration by default when you first open the solution in the Visual Studio GUI. If you build Slicer in release mode and accidentally forget to switch the build configuration to Release then the build will fail. Note: you can avoid this manual configuration mode selection by setting <code>CMAKE_CONFIGURATION_TYPES</code> to <code>Release</code> in cmake-gui.
** If building in debug mode:
*** Start Visual Studio using the Slicer launcher as described in [[Documentation/{{documentation/version}}/Developers/Tutorials/Debug_Instructions|Step-by-step debug instuctions]]
** Build the ALL_BUILD project

==== Unix-like ====
*'''Recommended''':
** Configure using the following commands. By default '''CMAKE_BUILD_TYPE''' is set to '''Debug'''.
<pre>
mkdir Slicer-SuperBuild-Debug
cd Slicer-SuperBuild-Debug
cmake -DCMAKE_BUILD_TYPE:STRING=Debug -DQT_QMAKE_EXECUTABLE:FILEPATH=/path/to/QtSDK/Desktop/Qt/486/gcc/bin/qmake ../Slicer
</pre>
where you replace ''/path/to/QtSDK'' with the real path on your machine where QtSDK is located

If '''using Qt from the system''', do not forget to add the following CMake variable to your configuration command line:
<pre>-DSlicer_USE_SYSTEM_QT:BOOL=1
</pre>

* '''Remarks''':
# Instead of <code>cmake</code>, you can use <code>ccmake</code> or <code>cmake-gui</code> to visually inspect and edit configure options.
# Using top-level directory name like <code>Slicer-SuperBuild-Release</code> or <code>Slicer-SuperBuild-Debug</code> is recommended.
# [[Documentation/{{documentation/version}}/Developers/Tutorials/Debug_Instructions|Step-by-step debug instuctions]]

* On Mac OS X 10.9 (Mavericks) / 10.10 (Yosemite) / 10.11 (El Capitan), also set the following variables (see [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2014/thread.html#16440 discussion]):
{| border="0" cellpadding="4" cellspacing="4"
|- 
| bgcolor="#abcdef" height="8" |  '''Variable'''
| bgcolor="#abcdef" height="8" |  '''Description'''
|-
| Slicer_USE_PYTHONQT_WITH_TCL || OFF
|-
| CMAKE_OSX_DEPLOYMENT_TARGET  || 10.9 or 10.10 or 10.11
|-
|}

=== General information ===

Two projects are generated by either <code>cmake</code>, <code>ccmake</code> or <code>cmake-gui</code>. 

One of them is in the top-level bin directory <code>Slicer-SuperBuild</code> and the other one is in the subdirectory <code>Slicer-build</code>:

<pre>Slicer-SuperBuild/Slicer-build</pre>

# The first project in <code>Slicer-SuperBuild</code> manages all the external dependencies of Slicer (VTK, ITK, Python, ...). To build Slicer for the first time, run make (or build the solution file in Visual Studio) in <code>Slicer-SuperBuild</code>, which will update and build the external libraries and if successful will then build the subproject Slicer-build.<br>
# The second project in <code>Slicer-SuperBuild/Slicer-build</code> is the "traditional" build directory of Slicer.  After local changes in Slicer (or after an svn update on the source directory of Slicer), only running make (or building the solution file in Visual Studio) in <code>Slicer-SuperBuild/Slicer-build</code> is necessary (the external libraries are considered built and up to date). <br>
#'''Warning''': An significant amount of disk space is required to compile Slicer in Debug (>10GB on Windows)

=== Workaround for if the firewall is blocking git protocol ===
* Some firewalls will block the git protocol. A possible workaround is to configure Slicer by disabling the option <code>Slicer_USE_GIT_PROTOCOL</code>. Then the http protocol will be used instead. Consider also reading https://github.com/commontk/CTK/issues/33