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

= 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:
 1. Give the utility a project name
 2. Link the python scripts to the location they are referenced by the Bash wrapper
 3. Install the wrapper script into `$FREESURFER_HOME/bin`
 4. 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.