Differences between revisions 183 and 184

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.

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.

-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-#pragma section-numbers on

#acl WikiUserGroup:read,write,delete,revert All:read
+#acl LcnGroup:read,write,delete,revert All:read
-Line 4:
+Line 3:
-'''Index'''
+= FreeSurfer Dev Guide =
-Line 6:
+Line 5:
-<<TableOfContents>>
+ * 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.
-Line 8:
+Line 9:
-This page is targeted at Martinos Center users who wish develop within the Freesurfer code base and possibly contribute changes. Martinos and non-Martinos users who simply want to clone the repo and build on their home machine, but dont plan on contributing changes, should consult the [[http://surfer.nmr.mgh.harvard.edu/fswiki/freesurfer_linux_developers_page|read-only git repo]]. Lastly, users who just want access to the code can clone directly from the official freesurfer github page:
+== Adding a New C Program ==
-Line 10:
+Line 11:
- https://github.com/freesurfer/freesurfer



=== Getting the Source Code ===



In order to contribute changes to Freesurfer, a specific setup procedure needs to be followed where a users forks the Freesurfer github repository, clones the fork, and submit pull requests. This is described in detail here:



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





=== Building ===



Once the source code has been cloned the next step is building it. The steps required to building the Freesurfer code base are described below:



==== 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.
+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:
-Line 28:
+Line 14:
-./setup_configure
+freesurfer/

    mri_process/

        CMakeLists.txt

        mri_process.cpp
-Line 31:
+Line 20:
-==== 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:
+In order to configure our new code, we should add the following to the empty `CMakeLists.txt` file.
-Line 36:
+Line 23:
-## Default configuration

./configure
+project(mri_process)
-Line 39:
+Line 25:
-## Specify an installation location

./configure --prefix=~/freesurfer_install_dir
+include_directories(${FS_INCLUDE_DIRS})
-Line 42:
+Line 27:
-## See all possible options

./configure --help
+add_executable(mri_process mri_process.cpp)

target_link_libraries(mri_process utils)



install(TARGETS mri_process DESTINATION bin)
-Line 46:
+Line 33:
-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/bin

}}}



During configure, if you receive a pax warning regarding archive names, you can suppress the issue by creating the following wrapper script called "pax" and adding it to the beginning of your PATH:



{{{

#!/bin/sh

#!/bin/sh

/usr/bin/pax -O "$@"

}}}



==== 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).



==== 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.



=== 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 [[DevelopersGuide_git#Building|building steps from above]] to verify your binary compiles and builds successfully.



=== Working with git (Examples) ===



==== Adding a new script ====

{{{

git pull upstream

git checkout –b nf-bay3-scripts

<make changes>

git add process_exvivo_diff_data_bay3.sh Makefile.am (all files related to commit)

git commit –m “Added script to process exvivo diffusion data.”

git push origin

}}}







----

Send your comments/questions/feedback to zkaufman@nmr.mgh.harvard.edu
+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.