#acl LcnGroup:read,write,delete,revert All:read

= FreeSurfer Build Guide =

This page walks through the process of building the freesurfer source code. For an introduction to the repository and the development process, visit the DevelopersGuide.

Freesurfer depends on a variety of third-party tools, and the BuildRequirements page recommends the easiest ways to install these dependencies on your machine. External developers should make sure they correctly set up the freesurfer packages directory as instructed.

== Source ==

Clone the freesurfer source code from github. If you're planning to commit changes to the main repository, make sure you clone from a forked repository instead and follow the recommended development cycle.

{{{
git clone git@github.com:freesurfer/freesurfer.git
}}}

==== Annex Data ====

The freesurfer repository contains many large binary files that can't be stored directly on github. The data can be retrieved from our server with git-annex, but the data source must first be setup as a remote repository. For those developing on the Martinos filesystem, cd into your repository and run:

{{{
git remote add datasrc file:///space/freesurfer/repo/annex.git
}}}

For those developing outside of Martinos, run:

{{{
git remote add datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git
}}}

Then, to download the annex data, run the following from the top-level directory:

{{{
git fetch datasrc
git-annex get .
}}}

Further annex instructions can be found on the GitAnnex page.

== Configuration ==

Freesurfer supports both in-source and out-of-source builds using CMake. To configure a simple in-source build tree, enter the top-level directory of the repository and run:

{{{
cmake .
}}}

'''NOTE:''' If you would like to completely re-configure a build, be sure to delete the `CMakeCache.txt` file from the top-level build directory.

==== Install Path ====

By default, freesurfer will install to `/usr/local/freesurfer`, but the install path can be configured with:

{{{
cmake . -DCMAKE_INSTALL_PREFIX="/path/to/desired/install"
}}}

Alternatively, this path can be set in an `FS_INSTALL_DIR` environment variable to avoid having to specify it for every configuration.

==== Packages ====

Users not developing on the Martinos filesystem will get an error indicating that external developers must provide a valid `FS_PACKAGES_DIR` path. To resolve this, you must point cmake to the full path of your packages directory (configured via the BuildRequirements instructions) with the following option:

{{{
cmake . -DFS_PACKAGES_DIR="/path/to/packages"
}}}

This path can also be set in an `FS_PACKAGES_DIR` environment variable, so that it doesn't need to be supplied on the command line for every new configuration.

==== Optimization and Debugging ====

By default, the freesurfer build type is set to ''Release'', which configures `-O3` optimization with no debugging. To build with debugging turned on, configure the `CMAKE_BUILD_TYPE` variable to equal `Debug` or `RelWithDebInfo`, like so:

{{{
cmake . -DCMAKE_BUILD_TYPE="Debug"
}}}

== Building ==

Once your build tree has been configured appropriately, freesurfer can be compiled with `make` and installed with `make install`. Additionally, unit and regression tests can be run with `make test` from individual subdirectories or from the top-level build directory.