macOS

Prerequisites

The prerequisites listed below are required to be able to configure/build/package/test Slicer.

  • XCode command line tools must be installed:

xcode-select --install

  • A CMake version that meets at least the minimum required CMake version here

  • Qt 5: tested and recommended.

    • For building Slicer: download and execute qt-unified-mac-x64-online.dmg, install Qt 5.15.2, make sure to select the qtwebengine component.

    • For packaging and redistributing Slicer: build Qt using qt-easy-build

  • Setting CMAKE_OSX_DEPLOYMENT_TARGET CMake variable specifies the minimum macOS version a generated installer may target. So it should be equal to or less than the version of SDK you are building on. Note that the SDK version is set using CMAKE_OSX_SYSROOT CMake variable automatically initialized during CMake configuration.

Checkout Slicer source files

Notes:

  • While it is not enforced, we strongly recommend you to avoid the use of spaces for both the source directory and the build directory.

  • Due to maximum path length limitations during the build process, build folders must be located in a location with very short total path length. This is especially critical on Windows and macOS. For example, /opt/s has been confirmed to work on macOS.

Check out the code using git:

  • Clone the github repository

git clone https://github.com/Slicer/Slicer.git

The Slicer directory is automatically created after cloning Slicer.

  • Setup the development environment:

cd Slicer
./Utilities/SetupForDevelopment.sh

Configure and generate Slicer solution files

  • Configure using the following commands. By default CMAKE_BUILD_TYPE is set to Debug (replace /path/to/Qt with the real path on your machine where QtSDK is located):

mkdir /opt/s
cd /opt/s
cmake \
  -DCMAKE_OSX_DEPLOYMENT_TARGET:STRING=11.0 \
  -DCMAKE_BUILD_TYPE:STRING=Debug \
  -DQt5_DIR:PATH=/path/to/Qt/lib/cmake/Qt5 \
  /path/to/source/code/of/Slicer

  • If using Qt from the system, do not forget to add the following CMake variable to your configuration command line: -DSlicer_USE_SYSTEM_QT:BOOL=ON

  • Remarks:

    • Instead of cmake, you can use ccmake or cmake-gui to visually inspect and edit configure options.

    • Using top-level directory name like /opt/sr for Release or /opt/s for Debug is recommended. If /opt does not exist on your machine you need to use sudo for mkdir and chown in /opt.

    • Step-by-step debug instructions

    • Additional configuration options to customize the application are described here.

General information

Two projects are generated by either cmake, ccmake or cmake-gui. One of them is in the top-level bin directory /opt/s and the other one is in the subdirectory Slicer-build:

  • /opt/s manages all the external dependencies of Slicer (VTK, ITK, Python, …). To build Slicer for the first time, run make in /opt/s, which will update and build the external libraries and if successful will then build the subproject Slicer-build.

  • /opt/s/Slicer-build is the “traditional” build directory of Slicer. After local changes in Slicer (or after an git update on the source directory of Slicer), only running make in /opt/s/Slicer-build is necessary (the external libraries are considered built and up to date).

Warning: An significant amount of disk space is required to compile Slicer in Debug mode (>20GB)

Warning: Some firewalls will block the git protocol. See more information and solution here.

Build Slicer

After configuration, start the build process in the /opt/s directory

  • Start a terminal and type the following (you can replace 4 by the number of processor cores in the computer. You can find out the number of available cores by running sysctl -n hw.ncpu):

cd ~/opt/s
make -j4

Run Slicer

Start a terminal and type the following:

/opt/s/Slicer-build/Slicer

Test Slicer

After building, run the tests in the /opt/s/Slicer-build directory.

Start a terminal and type the following (you can replace 4 by the number of processor cores in the computer):

cd /opt/s/Slicer-build
ctest -j4

Package Slicer

Warning: Slicer will only create a valid package that will run on machines other than it’s built on if Qt was built from source.

Start a terminal and type the following:

cd /opt/s
cd Slicer-build
make package

Debugging the build process

When using the -j option, the build will continue past the source of the first error. If the build fails and you don’t see what failed, rebuild without the -j option. Or, to speed up this process build first with the -j and -k options and then run plain make. The -k option will make the build keep going so that any code that can be compiled independent of the error will be completed and the second make will reach the error condition more efficiently. To debug the error you can pipe the output of the make command to an external log file like this:

make -j10 -k; make 2>&1 | tee /tmp/build.log

In some cases when the build fails without explicitly stating what went wrong it’s useful to look at error logs created during building of individual packages bundled with Slicer. Running the following command in the /opt/s folder

find . -name "*rr*.log" | xargs ls -ltur

will list such error logs in ordered by the time of latest access. The log that was accessed the last will be the lowest one in the list.

error while configuring PCRE: “cannot run C compiled program”

If the XCode command line tools are not properly set up on macOS, PCRE could fail to build in the Superbuild process with the errors like below:

configure: error: in `/Users/fedorov/local/Slicer4-Debug/PCRE-build':
configure: error: cannot run C compiled programs.

To install XCode command line tools, use the following command from the terminal:

xcode-select --install

dyld: malformed mach-o: load commands size (…) > 32768

Path the build folder is too long. For example building Slicer in /User/somebody/projects/something/dev/slicer/slicer-qt5-rel may fail with malformed mach-o error, while it succeeds in /opt/s folder. To resolve this error, move the build folder to a location with shorter full path and restart the build from scratch (the build tree is not relocatable).

Packaging errors

Fixing @rpath errors during packaging

If an error like

warning: target '@rpath/QtGui.framework/Versions/5/QtGui' is not absolute...
warning: target '@rpath/QtGui.framework/Versions/5/QtGui' does not exist...

is present during packaging - doublecheck that Slicer was built with Qt that was built from source and not Qt that was installed from a web-installer or homebrew.

Update Homebrew packages

Slicer can be installed with a single command using Homebrew, as described in the installation documentation.

Specifically, the cask extension is used, which allows management of graphical applications from the command line. Casks are Ruby files (.rb) describing the metadata necessary to download, check and install the package.

The cask for the Preview version of Slicer does not need maintenance, as it automatically downloads the latest binaries and therefore the exact version does not need to be specified in the cask. However, the cask for the stable version, which has traditionally been maintained by Slicer users, needs to be manually updated every time a new stable version of Slicer is released. Instructions to update Homebrew casks can be found on the homebrew-cask repository. This is an example of a command that can be used to update the cask for a Stable release:

$ brew bump-cask-pr --version 4.11.20210226,1442768 slicer

To install brew, the following command can be run:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Common errors

See list of issues common to all operating systems on Common errors page.