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.