This page is targeted at those who have access to the FreeSurfer source code, and wish to build this source code on their own Unix platform (whether it be an NMR Martinos Center platform, which has all required libraries, or on some arbitrary Unix platform, where the dependent libraries must be installed prior to building FreeSurfer).
1. CVS Checkout
If you have an NMR account, you can checkout the FreeSurfer source code from the NMR center using local CVS access or remotely by using SSH as the CVS remote connection method.
1.1. Local CVS Access
The CVS repository is /autofs/space/repo_001/dev. Use this as your CVSROOT. You can either set it as an environment variable:
setenv CVSROOT /autofs/space/repo_001/dev
or specify it in the checkout command with the -d option. Note that the CVS root is cached in a CVS checkout directory, so if you choose to use the -d method, you will only have to do it once during your first checkout.
Check out the code with the CVS checkout command. The archive name is dev.
cvs checkout -P dev
cvs -d /autofs/space/repo_001/dev checkout -P dev
This will copy the entire archive to your directory, creating a directory called dev/. The -P option will purge the old directories that have been removed from the CVS repository.
Generally it is handy to define an environment variable called FSDEV which is set to your Freesurfer development directory. Be sure also to define your FREESURFER_HOME environment variable set to the intended Freesurfer installation directory.
1.2. Remote CVS Access
Tell CVS to use SSH to access the archive by setting the following environment variable:
setenv CVS_RSH ssh
Use the following string as your CVS root:
setenv CVSROOT :ext:USER@MACHINE.nmr.mgh.harvard.edu:/autofs/space/repo_001/dev
Where USER is your username and MACHINE is one of the NMR machines visible to the outside ('door', not 'gate'). Then use the CVS commands normally.
Check out the code with the CVS checkout command. The archive name is dev.
cvs checkout -P dev
Note that using this method makes an SSH connection for every CVS command, and you will be required to enter your password every time. You may want to look into a utility to automatically authenticate SSH connections, such as SSH agent. See:
When working in a CVS checkout directory, cvs knows where the CVSROOT is for that directory. However, it doesn't know what CVS_RSH method to use, so if you are grabbing files remotely, you may want to set this in your login file.
2. Open Source Distribution
It is necessary to run a pre-configure script, to create the platform specific tools required by configure (execute in the dev/ directory created by cvs checkout):
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 'dev/config' directory.
Now you need to configure your building parameters for your machine:
This runs the configure script which checks a bunch of local settings and libraries that are needed. You will probably need to supply some extra options:
The prefix option determines where your build will be installed when you use the 'make install' command. This is your private copy of FreeSurfer, not a release for others, so put it in your own directory space. Generally, a developer will set their $FREESURFER_HOME to their working directory (in this case FREESURFER_HOME is ~/work/freesurfer). Note: Do not install freesurfer in the same directory as the source. In-source building is not supported.
If you are compiling in the NMR Center, pass the option:
This will look for and install some files that are only usable in the Center. These files are not included in external (open-source) release, so using this option on an external release will result in an error as required files will not be found.
There are options to specify where certain packages exist, such as: --with-mni-dir=/usr/pubsw/packages/mni/current These are often needed so configure can find libraries installed in /usr/pubsw. Note that you should have /usr/pubsw mounted on your machine. This is normal for NMR computers.
Freesurfer builds against the following set of open-sourced libraries, thus, these must be installed prior to building:
- MNI 1.4
- VXL 1.13.0
These must be installed if you want to build the GUI apps:
- Tcl 8.4.6
- Tk 8.4.6
- Tix 8.1.4
- BLT 2.4z
- VTK 5.6
- KWWidgets - CVS checkout
- Qt 3
If these libraries are not available on your system, then they must be built and installed. Special bundles of this open-source code are available on the distribution site:
If you do not have a set of libs, then in the src directory are the .tar.gz files containing the open-source code from which they can be built. The files tcltktixblt.tar.gz and mni-1.4-srcbuild.tar.gz each contain special build scripts that perform the work of building and installing these libraries. Refer to those scripts (with 'build_' in the filename preface) to see what they do. The VXL and VTK source requires cmake to build. Refer to the VXL home page and the notes below for build instructions. For the simplest installation, it is recommended to install these packages in a directory called /usr/pubsw/packages, as the Freesurfer setup script checks for this directory for its packages during its setup. Here is a table of recommended installation paths and build notes for the 3rd-party packages:
Suggested install path:
<get from VTK home>
An important note on building VXL and ITK on the 32b platform: the cmake file should include the following:
CMAKE_CXX_FLAGS -msse2 -mfpmath=sse CMAKE_C_FLAGS -msse2 -mfpmath=sse
The SSE instructions are used so that 32b platform results match those on the 64b platform (which uses SSE by default).
Freesurfer also builds against certain packages of the MINC toolkit. A special bundle of the MINC toolkit source code for the MINC packages required by Freesurfer has been assembled at MGH and is available from the download site:
Look for mni-1.4-srcbuild.tar.gz, and mni.srcbuild.README.txt describes the build process.
You will also need the following tools, with the listed version:
- autoconf v2.59
- automake v1.9.6
- libtool v1.5.6
- cmake v2.4-patch 3
The source for these tools can be found in ftp://surfer.nmr.mgh.harvard.edu/pub/dist/fs_supportlibs.
A sample configure line for a Linux machine at the NMR center having appropriate NFS mount-points (ie. /usr/pubsw/packages):
./configure \ --enable-nmr-install \ --prefix="$FREESURFER_HOME"
A sample configure line for a MacOSX machine at the NMR center is:
./configure --enable-nmr-install \ --prefix=$FREESURFER_HOME \ --with-gl-dir=/usr/X11R6 \ --with-vtk-dir=/usr/pubsw/packages/vtk/current \ --with-vtk-cocoa-dir=/usr/pubsw/packages/vtk/5.6.0_Cocoa \ --with-boost-dir=/usr/pubsw/packages/boost/current \ --with-itk-dir=/usr/pubsw/packages/itk/3.16
Note the special with-vtk-cocoa-dir and with-itk-dir options which are specific to Mac platforms.
A sample configure line for a machine with packages installed in /usr/local/packages:
./configure \ --enable-nmr-install \ --prefix="$FREESURFER_HOME" \ --with-mni-dir="/usr/local/packages/mni/current" \ --with-vxl-dir="/usr/local/packages/vxl/current" \ --with-tcl-dir="/usr/local/packages/tcltktixblt/current" \ --with-vtk-dir="/usr/local/packages/vtk/current"
Before attempting to build and install the 3rd-party packages from source, it is recommended to just start by running the configure command and observe the errors. configure will tell you which packages are already installed on your system. Read the file config.log, generated by configure, for error messages. Don't include the --enable-nmr-install option if building using an open-source distribution, as that distribution doesnt contain the nmr specialties.
Be aware that the tcl/tk/tix/blt combo is particularly tricky. While many systems have tcl/tk installed, the tricky thing is getting tix and BLT to work with tcl/tk. Thus, our installation package (tcltktixblt.tar.gz) is the easiest route to successfully getting these four guys to work together. Also, if the --with-tcl-dir=DIR option is not included in the configure command, then the Tcl/Tk apps (tkmedit, tksurfer, tkregister, scuba and orient_mri) are not built.
Note for cluster builds: if building for a cluster, where the gui apps are not necessary, then the --with-tcl-dir and --with-vtk-dir options can be excluded (not included in the configure command). This will skip the dependency on those libs.
You can now run 'make', edit and build code, etc. The first thing you should do is 'make' to build libraries like libutils. (Note that all libs will be built to your local checkout directory.) To just build libutils, cd into utils/ and run make.
You can now compile individual programs or all of them at once. To compile all of them, just run 'make' from dev/. Binaries will automatically be placed in their individual subdirectories. Like this:
cd dev make -j 9
Handy hint: the -j 9 option to make tells it to run nine simultaneous make processes, which, if building on a multi-processor machine, can speed-up the build.
You may just want to compile one binary at a time, for instance, if you are developing an app. To do so, 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.
5. Adding a new binary to the tree
Assuming that you have a source file MYPROG.c that compiles into MYPROG and want to add it to the FreeSurfer tree:
1) Make the directory in dev and copy the source file there. Name the directory MYPROG and the source file MYPROG.c.
mkdir dev/MYPROG cp MYPROG.c dev/MYPROG
2) Tell the autotools to build your program when you type make from the top dir:
a) Modify dev/configure.in to add MYPROG/Makefile to the list of files in the definition of AC_OUTPUT (these are in roughly alphabetical order). Be sure to add a backslash at the end of line:
AC_OUTPUT( \ ... other files ... MYPROG/Makefile \ )
b) Modify dev/Makefile.am to add MYPROG to the SUBDIRS definition. (You can also alternatively add it to the end of MRISUBDIRS or MRISSUBDIRS if more appropriate.)
SUBDIRS= ... other directories ... MYPROG
c) Copy dev/dummy/Makefile.am into MYPROG/ and customize it, replacing 'dummy' with 'MYPROG'. Be sure to change:
bin_PROGRAMS = MYPROG
and also delete the notes that are there.
d) Copy in the additional testing file dev/dummy/myown.c. You can customize it for your test program later.
3) Run ./setup_configure from dev/. This runs aclocal, autoconf and automake. You should get no errors. If you do, make sure you followed the above instructions properly. Also try the AutoconfTroubleshooting page. Verify that this step worked by checking if MYPROG/Makefile.in was created.
4) Run ./configure with the parameters you previously used. To check these out, run head config.log from dev/, assuming you have run configure successfully on some prior occasion. The output should include the ./configure line you used. Copy it, but leave out the --no-create --no-recursion options if present.
[dev/]$ head config.log This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. It was created by Freesurfer configure dev3, which was generated by GNU Autoconf 2.59. Invocation command line was $ ./configure --prefix=/space/minerva/1/users/nicks/freesurfer \ --with-mni-dir=/usr/pubsw/packages/mni/current \ --with-vxl-dir=/usr/pubsw/packages/vxl/current \ --with-tcl-dir=/usr/pubsw/packages/tcltktixblt/current \ --with-tixwish=/usr/pubsw/packages/tcltktixblt/current/bin/tixwish22.214.171.124 ## --------- ## ## Platform. ## [dev/]$ /configure --prefix=/space/minerva/1/users/nicks/freesurfer \ --with-mni-dir=/usr/pubsw/packages/mni/current \ --with-vxl-dir=/usr/pubsw/packages/vxl/current \ --with-tcl-dir=/usr/pubsw/packages/tcltktixblt/current \ --with-tixwish=/usr/pubsw/packages/tcltktixblt/current/bin/tixwish126.96.36.199
Note: Do not just copy this example, use what's in your own config.log file!
5) Run make and verify that your binary program MYPROG/MYPROG was created.
6) Check in your changes (note: do not commit Makefile.in, only Makefile.am is necessary).
[dev/] cvs ci -m "Added MYPROG" configure.in Makefile.am [dev/] cvs add MYPROG [dev/] cd MYPROG [MYPROG/] cvs add Makefile.am MYPROG.c myown.c [MYPROG/] cvs commit -m "First checkin." Makefile.am MYPROG.c myown.c
To install all binaries and support files into your private FreeSurfer, use 'make install' from the toplevel dev/ directory, like this:
cd dev make install
This will make a directory called freesurfer/ in the directory specified by the --prefix option to configure, above. Note that if you do not specify this location, it will try to install to /usr/local, which you probably don't have permission to do. Even if you do, i.e. you are installing on a laptop, it's generally better to specify a prefix of /usr/local/freesurfer to keep everything in the same place.
Note that you can also run 'make release'. 'make install' makes and installs the NMR internal version of FreeSurfer, while 'make release' makes the public version which omits some stuff.
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 scuba/ directory will copy the scuba binary and its support script files to the proper locations. Running 'make install' from scripts/ will copy all the necessary scripts to the right location.
7. Using CVS
When you want to commit your changes, use the cvs commit command. However, you must first check to see if the file(s) in the archive have changed since the last time you checked them out. To do so, run the cvs update command on the files you have changed. The -P option will purge (remove) files that have been removed from the CVS.
cvs update -P
If any have changed, you will see the letter U followed by the file name.
This means somebody else committed a newer version of the file, and your copy was just updated.
If you and somebody else have made changes on the same file that conflict each other, you will see the letter C along with a message about the conflicts.
If the message states the conflicts have been resolved, you don't have to worry: cvs has merged the differences properly. If it says it couldn't merge the differences, you need to open the file in question, search for the string >>>, and merge the differences yourself.
Once the up to date check has been performed, you can commit your changes. If you are in a directory and want to commit all the files in that directory that you have changed, just use:
This will commit changes in the current directory and any subdirectories. If you want to commit only certain files, use:
cvs commit <filename>
Or you can only commit the code in the current directory with the -l switch:
cvs commit -l
Each time, an editor will open and ask you to enter a log message. To bypass this, use the -m option and enter your log message on the command line:
cvs commit -m "some descriptive changelog comment" <filename>
A synonym for commit is ci, so you can just:
cvs ci -m "fixed stuff" <filename>
Periodically, you should update your working copy to be in sync with the archive. CVS will look at all your files and see if the ones in the archive are different. If so, it will update your copy. CVS will not delete local modifications you have made. To do this update:
cvs update -d -P
The -d switch adds any new directories and is not strictly necessary, but is a good habit, because if you don't use it you will update existing files but will now add new directories. The -P option purges directories of files that have been removed in the past.
Similarly, you can update an entire directory or a single file. To commit all the code in the current directory (code that has not been changed will not be commited):
cvs ci -m "fixed many things"
To restore an edited version to the version in the archive, either delete the file and cvs update, and the archive version will be copied to the local work area, or use the -C option to cvs update to replace your copy with one from the archive.
To add a new file to the archive, use the add command and then commit the file:
cvs add <filename> cvs commit -m "added the file" <filename>
To remove a file, remove in cvs and locally (with the -f flag), and commit:
cvs remove -f <filename> cvs commit -m "removed the file" <filename>
That covers most of the CVS commands you'll have to to use.
To tag a group of code with a text label:
cvs tag alpha-1
To retrieve a tagged group of code:
cvs update -r alpha-1
There are more useful commands, but these are the most commonly used ones. See http://www.cvshome.org for more info.
For more info on CVS, check out www.cvshome.org or the CVS man pages.
check in a file
get newest versions. merges newer versions than the ones you had with your working versions.
cvs update -A
tag working files:
cvs tag -c tag-name
if any working copies are edited, will report an error. check in first.
checkout a tag:
cvs checkout -r tag-name archive
split off a branch based on current revisions in working copy:
cvs tag -b branch-name
note: doesn't make working copy the branch.
split off a branch:
cvs rtag -b -r tag-name branch-name archive
check out a branch:
cvs checkout -r branch-name archive
switch working copy to a branch:
cvs update -r branch-name archive
BCD archive; cvs update -r branch-name
to find out what branch the working copy is on:
look for sticky tag field.
join the changes in a branch to current working copy:
cvs update -j branch-to-join file
best to tag merged branches after every merge.
joing the changes in a revision to current working copy:
cvs update -j rev file
i.e. two people check out 1.3, someone checks it in 1.4, you try to check it in and get a conflict, can join in the changes with cvs update -j 1.4 file.c
add a new file:
cvs add file; cvs commit file
remove a file (but keep in older revisions):
rm file; cvs remove file; cvs commit file
rename a file:
mv old new; cvs remove old; cvs add new; cvs commit old new
To receive an email notification about any file that has been commited by somebody else:
cd dev cvs watch add
To undo this, and disable receiving an email notification about files that have been commited, type:
cd dev cvs watch remove
See also: DevelopersGuide/CVSTips
8. Troubleshooting autoconf issues
9. Martinos Center issues
see Martinos Center issues page
Note: On this page, there are also instructions on how commit messages can be sent to an additional person for documentation purposes, etc.
10. Coding Guide
This page deals specifically with coding issues.
11. Docs and Testing
12. Developing for a Mac
Info can be found here.