Index

This page is targeted at Martinos Center users who wish to inspect, build or develop within the Freesurfer code base. Non-Martinos users wishing to work with the Freesurfer code base should consult the read-only git repo.

1. Getting the Source Code

note: If you plan on actually contributing to the freesurfer repository, you should ignore this step and follow the instructions at freesurfer_github to setup a github fork.

The first thing users at the Martinos Center need to do is prepend the directory /usr/pubsw/packages/git-annex/current/bin to their PATH. Once that is done, the Freesurfer source code can be cloned from the official Freesurfer github page:

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

1.1. Get the Data Files

The Freesurfer repository contains a large number data files which are not included with a default git clone of the repo. Instead, these data files are distributed via the git-annex software. Users who only want the repository for the purposes of compiling binaries and/or inspecting source code, the git clone command from above is all you need to do. Users who want to run build time checks, or perform a full local installation, or just want all the contents of the repository, will need to add a special data store remote repository in order to retrieve these files.

To add the data store repository (this only needs to be done once):

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

And to retrieve data files:

git annex get <filename>

The data files have been broken down into categories, those being required for build time checks, those required for a local installation, and everything else. Use one of the following commands depending on your needs:

## Get only the data files required for build time checks (1.9 GB)
git annex get --metadata fstags=makecheck .

## Get only the data files required for local installation (4.3 GB)
git annex get --metadata fstags=makeinstall .

## Just give me everything! Not Recommended (6.8 GB)
git annex get .

2. Building

2.1. Setup Configure

It is necessary to run a pre-configure script, to create the platform specific tools required by configure (execute in the freesurfer directory created by git clone). This script runs a set of commands (aclocal, libtoolize, automake v1.9.6, autoconf v2.59) that creates the platform specific files for configure and puts them in the 'fsdev/config' directory.

./setup_configure

2.2. Configure

Now you need to configure your building parameters for your machine by running the configure script. Users at the Martinos Center should for the most part be fine with the default settings, but the configure script does accept many options for pointing to specific libraries and other build specific parameters. One exception is if a user wants to perform a local installation of FreeSurfer, he/she should use the --prefix flag. Type ./configure --help for a full list of options. For example:

## Default configuration
./configure

## Specify an installation location
./configure --prefix=~/freesurfer_install_dir

## See all possible options
./configure --help

Freesurfer builds against the following set of open-sourced libraries, which are installed under the /usr/pubsw/packages directory on all NMR computers:

• Package	Version		Package	Version
  CUDA	v5.0.35-rh5		ANN	v1.1
  tiffjpegglut	v3.6, v6b, v3.7		itk	v3.16
  VTK	v5.6		VXL	v1.14
  MNI	v1.5		tcltktixblt	v8.4, v8.4, v8.1, v2.4z
  KWWWidgets	CVS checkout		Qt	v4.7
  wxWidgets	v2.8		cppunit	v1.10
  xawplus	v3.1		petsc	v2.3

All these packages will be found by default by the ./configure script. But there are options to specify where certain packages exists if a user wishes to build against a different version of one of the open-source libraries. For example:

## Specify a specific version of qt
./configure --with-qt=/usr/pubsw/packages/qt/4.8.5

2.3. Compile

You can now run 'make' to build the all individual programs in the FreeSurfer source tree. Binaries will automatically be placed in their individual subdirectories.

make -j 4

Handy hint: the -j 4 option to make tells it to run four simultaneous make processes, which, if building on a multi-processor machine, can speed-up the build.

If you want to compile just one binary at a time, for example, if you are developing an app, than cd to the directory of the program you want and use 'make' to compile it:

cd mri_info
make

This creates mri_info in the mri_info/ directory. However, be aware the many program depends on the existence of libraries having already been build like libutils. Therefore users will need to build a few of the library directories first (e.g. utils, fsgdf, xml2, etc).

2.4. Install

To initial a local installation, type 'make install' from the top level directory:

make install

This will create a local Freesurfer installation in the directory as specified by the --prefix option to configure script (see above). Note that if you do not specify this location, it will try to install to /usr/local, which will probably require root access. The first time you run 'make install', it will take a while to copy all the big data files to the new installation. Subsequent 'make installs' will only copy the changed files.

If you only want to install a single binary, run 'make install' from a subdirectory. For example, running 'make install' from the mri_convert directory will copy the mri_convert binary to the proper locations. Running 'make install' from scripts/ will copy all the necessary scripts to the right location.

3. Adding a new binary to the tree

For this example we will assume you want to create a program called 'MYPROG' and want to add it to the FreeSurfer tree:

1) Make a directory called MYPROG under the freesurfer directory, and put your source code there. In the simplest case you will have a single source code file called MYPROG.c.

## Create the MYPROG directory and 'cd' into it
mkdir MYPROG
cd MYPROG
## The MYPROG.c file goes here

2) Copy freesurfer/dummy/Makefile.am into MYPROG/ and customize it, replacing 'dummy' with 'MYPROG'. Also delete the notes that are there. Be sure to change:

bin_PROGRAMS = MYPROG

3) Modify configure.in to add MYPROG/Makefile to the list of files in the definition of AC_OUTPUT (these are in roughly alphabetical order).

## configure.in ##

AC_OUTPUT(
... <list of files> ...
MYPROG/Makefile
... <list of files> ...
)

4) Modify freesurfer/Makefile.am to add MYPROG to the MRISUBDIRS or MRISSUBDIRS definition. (You can also alternatively add it to the end of any of the *SUBDIRS categories.)

## Makefile.am ##

MRISUBDIRS= \
... <list of files> ...
MYPROG \
... <list of files> ...

Once these 4 steps are complete MYPROG should automatically be built with the rest of FreeSurfer. Try following the building steps from above to verify your binary compiles and builds successfully.

4. Contributing Changes

Users who with to contribute to the Freesurfer code base and/or commit changes to the repo should see the following page which describe how to fork the freesurfer repository and submit pull requests:

• https://surfer.nmr.mgh.harvard.edu/fswiki/Freesurfer_github