FreeSurfer Dev Guide

Visit the BuildGuide for instructions on building and installing freesurfer manually.
Visit the GitHub page for an introduction to the github workflow.
Visit the GitAnnex page for detailed instructions on using git annex for storing and retrieving large data files in the repository.

File Size Limitations

Any files larger than 50MB should be stored in the GitAnnex, following the hyperlinked instructions, and properly linked to your utility.

Adding a New C Program

If you'd like to add a new program to the tree, you should create a new subdirectory with the title of your tool. As an example, let's create a new c++ program called mri_process. First, we'll create a top-level subdirectory that contains our new c++ file and an empty CMakeLists.txt file:

freesurfer/
    mri_process/
        CMakeLists.txt
        mri_process.cpp

In order to configure our new code, we should add the following to the empty CMakeLists.txt file.

project(mri_process)

include_directories(${FS_INCLUDE_DIRS})

add_executable(mri_process mri_process.cpp)
target_link_libraries(mri_process utils)

install(TARGETS mri_process DESTINATION bin)

This will compile mri_process.cpp, link it against the utils freesurfer library, and copy the executable to the $FREESURFER_HOME/bin directory during install. To include this subdirectory in the main freesurfer build, make sure to modify the top-level CMakeLists.txt by adding mri_process to the long list of included directories at the bottom of the file. Now, after reconfiguring your build, you can run make in the mri_process directory of your build tree to successfully compile the new program. If you're having trouble configuring and building freesurfer, be sure to visit the BuildGuide for step-by-step instructions.

Adding a New Python Program

Adding a new python program is similar to adding a new c++ program, with an additional step of creating a bash wrapper to be installed in $FREESURFER_HOME/bin.

Note: Make sure all paths in the Bash wrapper that reference files in the FreeSurfer file tree are defined relative to $FREESURFER_HOME, to ensure they are found regardless of the install location

As an example, let’s add a program called mri_process to the FreeSurfer tree, where the main functionality is in a python script called mri_process.py, and has a dependency on a model called process_model.h5.

First, we’ll create a directory containing the scripts, dependencies, and CMakeLists.txt:

freesurfer/
        mri_process/
                CMakeLists.txt
                mri_process.sh          # shell wrapper to install in bin/
                process_model.h5        # model dependency stored in the annex
                python/                 # dir containing the python code
                        mri_process.py  # python script called by shell wrapper

Now we’ll need to populate the empty CMakeLists.txt file. We need to achieve the following in this file:

Give the utility a project name
Link the python scripts to the location they are referenced by the Bash wrapper
Install the wrapper script into $FREESURFER_HOME/bin
Link any models to the proper location to be accessible to the python code

An example CMakeLists.txt:

project(mri_process)

install_symlinks(python/mri_process.py TYPE files DESTINATION python/scripts)

install_configured(mri_process.sh DESTINATION bin)

install_symlinks(process_model.h5 TYPE files DESTINATION models)

Finally, we need to add this directory to the list of included directories in the CMakeLists.txt located at the top level of the FreeSurfer file tree. To add your new utility to your build of FreeSurfer, reconfigure your build, and run make in the mri_process directory. You can also rebuild all of FreeSurfer with your new utility if needed. More information on building Freesurfer is located in the BuildGuide.