Navigation(children)

Index

TableOfContents

1. Medical Image Format FAQ

[http://www.dclunie.com/medical-image-faq/html Medical Image Format FAQ]

2. CVS Checkout

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.

2.1. Local CVS Access

The CVS repository is /space/repo/1/dev. Use this as your CVSROOT. You can either set it as an environment variable:

setenv CVSROOT /space/repo/1/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

or

cvs -d /space/repo/1/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.

2.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:

:ext:USER@MACHINE.nmr.mgh.harvard.edu:/space/repo/1/dev

Where USER is your username and MACHINE is one of the NMR machines visible to the outside, i.e. gate, entry, or door. Then use the CVS commands normally.

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:

http://mah.everybody.org/docs/ssh

3. Building

==== Required reading =====

Please check out the following files in the dev/ archive first: README-compiling.txt, README-releasing.txt

Note that for a new environment, before running configure, and anytime after a Makefile.am file has changed, the following commands must be executed within the dev/ directory:

rm -rf autom4te.cache
aclocal
libtoolize --force
autoreconf --force
autoconf

The first three commands create the platform specific tools needed by configure (use glibtoolize on the Mac in place of libtoolize). These platform specific tools are placed in the dev/config directory. Autoreconf --force creates the Makefile.in files from the Makefile.am files in each directory. The autoconf is redundant, as it normally runs within autoreconf --force, but the notes say that it is not gauranteed, so it should be run to be sure.

Following those commands, the configure command can be executed. Here's a generic example, where $FREESURFER_HOME is the intended installation directory:

./configure --prefix=$FREESURFER_HOME

Again, be sure to read the following files in the dev/ archive first: README-compiling.txt, README-releasing.txt

3.1. 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 at the end of the file in the definition of AC_OUTPUT. 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 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

d) Copy in the additional testing file dev/dummy/myown.c. You can customize it for your test program later.

3) Run automake from dev/. You should get no errors. If you do, make sure you followed the above instructions properly. Also try the AutoconfTroubleshooting page. Verify that this stepped work by checking if MYPROG/Makefile.in was created.

4) Run autoconf to generate a new configure script that now includes your new MYPROG directory.

5) Run ./configure with the parameters you previously used. To check these out, run head config.log from dev/. 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 0.1, which was
generated by GNU Autoconf 2.57.  Invocation command line was

  $ ./configure --with-mni-dir=/usr/pubsw/packages/mni/current --prefix=/home/kteich/freesurfer/dev --no-create --no-recursion

## --------- ##
## Platform. ##
[dev/]$ ./configure --with-mni-dir=/usr/pubsw/packages/mni/current --prefix=/home/kteich/freesurfer/dev

Note: Do not just copy this example, use what's in your own config.log file!

6) Run make and verify that your binary program MYPROG/MYPROG was created.

7) Check in your changes.

[dev/] cvs ci -m "Added MYPROG" configure configure.in Makefile.am Makefile.in
[dev/] cvs add MYPROG
[dev/] cd MYPROG
[MYPROG/] cvs add Makefile.am Makefile.in MYPROG.c myown.c
[MYPROG/] cvs commit -m "First checkin." Makefile.am Makefile.in MYPROG.c myown.c

3.2. autoconf Troubleshooting

Here's a list of common problems and solutions for autotools problems:

[AutoconfTroubleshooting]

3.3. Making changes live

The current setup allows you to have your own private installation of FreeSurfer using configure --prefix=/your/private/directory. This lets you use make install to easily install the entire FreeSurfer environment into a local copy.

The purpose of having your own private installation of FreeSurfer is to use it as a testbed to make sure that (1) your updates, whatever they be, work in freesurfer/ setup that is just like a real one, and (2) your updates are properly installed using 'make install' and 'make release'. Once you are sure of these two things, check in your updated files, including any Makefile.am and Makefile.in changes, etc, and the nightly build script will take care of the rest.

The nightly build stuff automatically updates and installs the dev/ distribution on all seven build platforms. The next morning, just check if your changes are in any /usr/local/freesurfer/dev; if not, notify me. If they are in one /usr/local/freesurfer, they will be in the rest of them. (If any build/installs fail, I am notified, and will do the build/install manually for that day.)

Things not to do:

- Don't test your local setup by manually copying files into your local freesurfer/. Otherwise you can't be sure that the automated build will correctly install your files with 'make install' and 'make release'. The only way files should get into your freesurfer/ distro as with 'make install' and 'make release'.

- Don't try to install into /usr/local/freesurfer yourself (i.e. by setting your .configure --prefix=... to target it). It's set up so the build scripts can do their job automatically. Also, you would only be installing on one of the seven platforms. It's a pain to do all three builds on all build machines and verify it all worked - that's what the nightly build script is for, so let it do it for you.

If you absolutely need a 'hot fix' right away, and need to make changes live in any of the /usr/local/freesurfers before the nightly build stuff goes, let KevinTeich know and he'll do it.

3.4. How the nightly build works

First a note on the directory structure. In /space/birn/50/freesurfer/build there is a directory for each build machine. Each builds a platform in /space/birn/50/freesurfer, i.e. /space/birn/50/freesurfer/rh7.3. Currently these are as follows:

Inside each /space/birn/50/freesurfer/build/MACHINE is trunk/ and stable/, as well as directories for local Qt installs and on Panther, MNI, and files for automated building. configure_options.txt contain command-line arguments for configure for that platform, and source_before_building.csh (optional) contains environment variables that must be set (mainly things like CPPFLAGS that are used by configure but can't be passed in to configure via the command line from a cronjob). The trunk and stable directories contain cvs checkouts.

In /space/birn/50/freesurfer/build/scripts is build_dev.csh and build_betapub.csh. Each build machine runs build_dev.csh nightly. It basically goes to /space/birn/50/freesurfer/build/MACHINE/trunk/dev and does the following:

cvs update -d
make distclean
rm -rf autom4te.cache
aclocal
autoconf
automake
./configure  `cat ${BUILD_DIR}/configure_options.txt` --prefix=/usr/local/freesurfer/dev
make
rm -rf freesurfer/bin_old
mv freesurfer/bin freesurfer/bin_old
make install

The build_betapub.csh works in /space/birn/50/freesurfer/build/MACHINE/stable/dev and also does:

make release prefix=/usr/local/freesurfer/pub

All the autotools stuff gaurantees that enough of the Makefiles will be regenerated to ensure that new directories will be added to all Makefiles. This wouldn't normally be done with a simple ./config.status because configure may need to be regenerated to know about new directories.

Currently (as of 4/8/2005) the build_betapub.csh script is not run regularly. This is to minimize interruption to the freesurfer/beta build.

Note that all machines can run these scripts at any time from the command line. This lets a maintainer (KevinTeich) explicity do a build and install on any machine if a 'hot fix' is needed.

Additionally, a developer can go to each machine's /space/birn/50/freesurfer/build/MACHINE/trunk/dev, update code, and do a make install from an individual binary directory if a hot fix is needed for a single binary before the nightly build. This is the quick and dirty way of doing an update for a single without waiting for the nightly build. For example, to update tkmedit, the developer would, for each build machine:

cd /space/birn/50/freesurfer/build/MACHINE/trunk/dev/tkmedit
cvs update
make install

This would install the files to /usr/local/freesurfer/dev. However, the developer must know about file dependencies. In this case, the script files that tkmedit may also need to be updated, so the developer would also have to cvs update and make install from dev/scripts.

4. RPM

[RpmInfo]