Building FreeSurfer From the Source
In this guide, we'll go over the steps required to build do a clean build of FreeSurfer from source.
We'll cover the following: - Installing Third Party Libraries And Package Dependencies - NOTE: If you're developing at the Martinos Center, you can likely skip this step if you are building on a machine that mounts /autofs. Rob D has set this for cluster users to speed up development/testing at the center. - Note: If you're developing at the Martinos Center and you need a different version of cmake, check under /usr/pubsw - #Cloning the FS source code - #Configuring and cloning the annex files - #Configuring the build - Note: we won't go over every single build option, just those that tend to be the most impactful - #Compiling and installing the FreeSurfer source - #Sourcing the new install of FreeSurfer
The instructions for each of these steps may vary slightly depending on the OS you are building on and whether or not you are developing on the Martinos cluster and can leverage the infrastructure Rob's built out. If the workflows differ between OS's, instructions for each OS will be provided.
If building at the Martinos Center, you can jump straight to #Cloning the FS source code.
Installing Third Party Libraries And Package Dependencies
FreeSurfer is supported on CentOS/Rocky Linux, Ubuntu, and MacOS. The package managers and names for the required libraries in the respective repos differ, so we'll cover each OS separately here.
CentOS/Rocky Linux Run the following to download the required libraries:
# make sure the system is up to date sudo yum update # install the libraries sudo yum install \ git \ wget \ tcsh \ gcc \ gcc-c++ \ libgfortran-static \ make \ vim-common \ lapack-devel \ lapack-static \ blas-devel \ blas-static \ zlib-devel \ python-devel \ python3-devel \ libX11-devel \ libXmu-devel \ mesa-libGL-devel
Ubuntu Run the following to download the required libraries:
# make sure the system is up to date sudo apt-get update # install the libraries sudo apt-get install \ git \ wget \ tcsh \ xxd \ build-essential \ gfortran \ libblas-dev \ liblapack-dev \ zlib1g-dev \ libxmu-dev \ libxmu-headers \ libxi-dev \ libxt-dev \ libx11-dev \ libglu1-mesa-dev
MacOS We recommend using the homebrew package manager on MacOS. Instructions for installing it can be found here Once you have installed homebrew run the following command to install the required libraries:
brew install gcc5 cmake tcsh libomp
Python Python is also required to build FreeSurfer, currently the development branch is being built with python 3.8.13, and it is recommended to build with python >= 3.8 to ensure that the ML based tools work properly. For managing python versions, we recommend using conda. It can be installed by following the instructions here, or if you prefer the miniforge distribution, it can be found here Once you have conda installed, you can create an environment with the desired version of python:
conda create -n <env_name> python=<python_version>
This command will create an environment named fs_build, with python 3.8.13:
conda create -n fs_build python=3.8.13
Qt The GUI's in FreeSurfer (ie FreeView) are built using the Qt framework. However, FreeSurfer can be built without the GUI component, more on this in #Configuring the build. To build FreeSurfer with GUI's, only the Open Source version of Qt is required.
Currently, we are building the GUI's with Qt 5.15. Downloads and instructions for setting up Qt can be found on their 'Getting Started' page here
Additional FreeSurfer Packages The remaining FreeSurfer dependencies, such as ITK and VTK can be downloaded as prebuilt packages (recommended), or they can be built locally using the build_packages.py script that ships as part of the FreeSurfer source, under freesurfer/packages/build_packages.py.
The location of the additional packages will need to be specified when configuring the build, more on this in #Configuring the build.
The prebuilt packages can be downloaded and installed via the following: Linux:
wget https://surfer.nmr.mgh.harvard.edu/pub/data/fspackages/prebuilt/centos7-packages.tar.gz tar -xzvf centos7-packages.tar.gz
Mac:
curl https://surfer.nmr.mgh.harvard.edu/pub/data/fspackages/prebuilt/osx10.11-packages.tar.gz -o osx10.11-packages.tar.gz tar -xzvf osx10.11-packages.tar.gz
The script to build the packages takes a single command line argument, the location where the packages will be installed.
build_packages.py </path/to/install/destination>
Cloning the FS source code
All code in the FreeSurfer code base is available on GitHub here The repo is public, so you shouldn't need any authentication.
Run the following to clone the FreeSurfer source tree into your PWD:
git clone git@github.com:freesurfer/freesurfer
This should have created a directory named freesurfer in your PWD, navigate into it to configure the annex files:
cd freesurfer
Configuring and cloning the annex files
Files that are needed to run FreeSurfer but do not contain source code or precompiled executables are distributed via git-annex. These include things like some atlas files and test/validation data for running unit/regression tests. FreeSurfer will fail to build if these files are not present.
From within the freesurfer dir that was created in the previous step, run the following to add the reference to the git-annex and pull down the required files:
# add the reference to the git-annex git remote add datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git # fetch any changes to the annex files git fetch datasrc # pull the most recent versions of the files git-annex get .
Configuring the build
Now that we have the all the third party libraries and packages, source code, and additional files, we have everything needed to build FreeSurfer. All that's left is to configure the build using cmake, then build and install it with make and make install. Tests can be run with make test.
cmake The cmake configuration should be run from within the freesurfer source tree that was previously cloned. cmake will read the CMakeFiles.txt on the top level of the freesurfer source tree. If the default options are sufficient, the build can be configured by simply running:
cmake
This will install freesurfer under /usr/local/freesurfer, without CUDA support for utilities that depend on pytorch or tensorflow, which may be undesirable.
User specified options to pass to cmake can be passed as args on the command line, prefixed with -D. The options that cmake will respect can be found in freesurfer/CMakeLists.txt. Most are specified in lines 40 - 60.
To find all the specifiable options, you can run:
cat freesurfer/CMakeLists.txt | grep option -n
This will print all the defined options with the line number, so they can be looked at in context.
Most commonly used cmake options: - -DMARTINOS_BUILD=[ON | OFF] - Set to ON if building on the Martinos cluster, set to OFF if building anywhere else - Default: ON - -DCMAKE_INSTALL_PREFIX=<path> - Location to install freesurfer, specified as a string - Default: /usr/local/freesurfer - -DFSPYTHON_INSTALL_CUDA=[ON | OFF] - Install versions of pytorch and tensorflow with CUDA support - Default: OFF - -DDISTRIBUTE_FSPYTHON=[ON | OFF] - Install the minimal python distribution, fspython that ships with freesurfer. If ON, install the minimal fspython distribution, if OFF use the system python installation - Default: OFF - -DCMAKE_BUILD_TYPE=[Release | Debug] - Build in Release or Debug mode, to build with debugging turned on, specify Debug - Default: Release - -DINFANT_MODULE=[ON | OFF] - Build the infant recon-all tools - Default: OFF - -DBUILD_GUIS=[ON | OFF] - Build GUI components, ie freeview - If set to OFF, Qt is not needed - Default: ON - -DQT_SYSLIBS=[ON | OFF] - ONLY USE IF -DMARTINOS_BUILD=ON - Use the native Qt libraries installed on the cluster - Default: OFF - -DAPPLE_ARM64=[ON | OFF] - Turn ON if building on a Mac platform with an ARM processor (Macs with the M series Apple Silicon) - Default: OFF - -DFS_PACKAGES_DIR=<path> - If not building on the Martinos cluster, this is the path where the additional package dependencies were installed from the build_packages.py script, or unpacked from the tarball - Default: "" The following is an example of a build configuration that will install the build in a directory called build, on the same level as the source tree, with CUDA support, and the infant FreeSurfer module:
cmake -DCMAKE_INSTALL_PREFIX=../build \ -DFSPYTHON_INSTALL_CUDA=ON \ -DINFANT_MODULE=ON
Compiling and installing the FreeSurfer source
Once cmake completes configuring the build, it can be compiled via make and installed via make install.
The make step will compile the executables from source and build the python bindings
make # run from the root of the freesurfer source tree
After the source is compiled, the unit and regression tests can be run via make test. This can be run from the root of the freesurfer source tree to run all tests. Alternatively, a specific test can be run by running make test from within that subdir. Run all tests:
make test # run from the root of the freesurfer source tree
Run a test for a specific utility:
cd lta_convert make test # only runs the test for lta_convert
To install the compiled binaries:
make install # run from the root of the freesurfer source tree
This will install the compiled executables, additional packages, atlases, subject data, etc. into the directory specified to -DCMAKE _INSTALL_PREFIX
Sourcing the new install of FreeSurfer
Now that FreeSurfer has been installed, we need to configure the environment for the tools to work properly. FreeSurfer requires a license to use, which can be obtained for free by filling out the registration form here.
Once you receive the license, it should be moved to the directory in which FreeSurfer was installed. For the default install path, this will be: /usr/local/freesurfer
FreeSurfer depends on several environment variables to operate correctly. The most important of which is FREESURFER_HOME, and points to the install location. The rest of the environment variables can be set automatically by sourcing the proper SetUpFreeSurfer.* script.
To source FreeSurfer, first set the value of FREESURFER_HOME to point to the install:
export FREESURFER_HOME=/usr/local/freesurfer
set FREESURFER_HOME=/usr/local/freesurfer
If the default install location was overwritten by specifying -DCMAKE_INSTALL_PREFIX, FREESURFER_HOME should point to that directory.
Once FREESURFER_HOME has been correctly set, the setup script can be sourced, there are versions for bash and tcsh shells:
source $FREESURFER_HOME/SetUpFreeSurfer.sh
source $FREESURFER_HOME/SetUpFreeSurfer.csh
This will set the rest of the environment variables needed by FreeSurfer, and it will add the FreeSurfer utilities to your system PATH To test that FreeSurfer has been correctly sourced, run the following:
which freesurfer
This should return the path to the $FREESURFER_HOME/bin/freesurfer