| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
|
#pragma section-numbers on #acl WikiUserGroup:read,write,delete,revert All:read '''Index''' <<TableOfContents>> This page is targeted at Martinos Center users who wish to inspect, build or develop within the Freesurfer code base. Non-Martinos users wishing to work with the Freesurfer code base should consult the [[http://surfer.nmr.mgh.harvard.edu/fswiki/freesurfer_linux_developers_page|read-only git repo]]. === Getting the Source Code === '''note:''' If you plan on actually contributing to the freesurfer repository, you should ignore this step and follow the instructions at [[https://surfer.nmr.mgh.harvard.edu/fswiki/Freesurfer_github|freesurfer_github]] to setup a github fork. The first thing users at the Martinos Center need to do is '''prepend''' the directory {{{/usr/pubsw/packages/git-annex/current/bin}}} to their PATH. Once that is done, the Freesurfer source code can be cloned from the official [[https://github.com/freesurfer/freesurfer|Freesurfer github page]]: {{{ git clone git@github.com:freesurfer/freesurfer.git }}} ==== Get the Data Files ==== The Freesurfer repository contains a large number data files which are not included with a default {{{git clone}}} of the repo. Instead, these data files are distributed via the [[https://git-annex.branchable.com/|git-annex]] software. Users who only want the repository for the purposes of compiling binaries and/or inspecting source code, the {{{git clone}}} command from above is all you need to do. Users who want to run build time checks, or perform a full local installation, or just want all the contents of the repository, will need to add a special data store remote repository in order to retrieve these files. To add the data store repository (this only needs to be done once): {{{ git remote add datasrc file:///space/freesurfer/repo/annex.git git fetch datasrc }}} And to retrieve data files: {{{ git annex get <filename> }}} The data files have been broken down into categories, those being required for build time checks, those required for a local installation, and everything else. Use one of the following commands depending on your needs: {{{ ## Get only the data files required for build time checks (1.9 GB) git annex get --metadata fstags=makecheck . ## Get only the data files required for local installation (4.3 GB) git annex get --metadata fstags=makeinstall . ## Just give me everything! Not Recommended (6.8 GB) git annex get . }}} === Building === ==== 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. {{{ ./setup_configure }}} ==== 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: {{{ ## Default configuration ./configure ## Specify an installation location ./configure --prefix=~/freesurfer_install_dir ## See all possible options ./configure --help }}} 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 }}} ==== 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. === Contributing Changes === Users who with to contribute to the Freesurfer code base and/or commit changes to the repo should see the following page which describe how to fork the freesurfer repository and submit pull requests: https://surfer.nmr.mgh.harvard.edu/fswiki/Freesurfer_github |
- Diff for "DevelopersGuide_git"