|
Size: 3993
Comment:
|
Size: 3465
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #acl LcnGroup:read,write,delete,revert All:read |
|
| Line 3: | Line 5: |
| This page walks through the process of building the freesurfer source code and creating a distribution. For an introduction to the repository and the development process, visit the [[DevGuide|Dev Guide]]. | This page walks through the process of building the freesurfer source code. For an introduction to the repository and the development process, visit the DevelopersGuide. |
| Line 5: | Line 7: |
| Freesurfer depends on a variety of third-party tools, and the BuildRequirements page recommends the easiest ways to install these dependencies on your machine. External developers should make sure they correctly set up the freesurfer packages directory as instructed. | |
| Line 6: | Line 9: |
| <<BR>> == Build Requirements == |
== Source == |
| Line 9: | Line 11: |
| Freesurfer depends on a variety of third-party packages, and the following recommends the easiest way to install these requirements on your machine. ''This section can be ignored by those developing on the Martinos filesystem.'' ==== Linux ==== On ubuntu/debian, install a few of the build dependencies with apt-get: |
Clone the freesurfer source code from github. If you're planning to commit changes to the main repository, make sure you clone from a forked repository instead and follow the recommended development cycle. |
| Line 18: | Line 14: |
| sudo apt-get update sudo apt-get install build-essential tcsh cmake gfortran \ libglu1-mesa-dev libfreetype6-dev uuid-dev \ libxmu-dev libxmu-headers libjpeg62-dev \ libxi-dev libx11-dev libxml2-utils libxt-dev \ libxaw7-dev liblapack-dev |
git clone git@github.com:freesurfer/freesurfer.git |
| Line 26: | Line 17: |
| If gcc4.8 or higher is not installed on your machine, run: | ==== Annex Data ==== The freesurfer repository contains many large binary files that can't be stored directly on github. The data can be retrieved from our server with git-annex, but the data source must first be setup as a remote repository. For those developing on the Martinos filesystem, cd into your repository and run: |
| Line 29: | Line 22: |
| ## install gcc/g++/gfortran version 4.8 sudo apt-get install gcc-4.8 g++-4.8 libgfortran-4.8-dev ## set as default compiler sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 50 sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.8 50 |
git remote add datasrc file:///space/freesurfer/repo/annex.git |
| Line 37: | Line 25: |
| The remaining dependencies can be built locally using the build_packages.sh freesurfer script, or they can just be downloaded as prebuilt packages (recommended). The following will create a `packages` directory containing a set of required freesurfer dependencies (built on centos7): | For those developing outside of Martinos, run: |
| Line 40: | Line 28: |
| curl https://surfer.nmr.mgh.harvard.edu/pub/data/fspackages/prebuilt/centos7-packages.tar.gz -o centos7-packages.tar.gz tar -xzvf centos7-packages.tar.gz |
git remote add datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git |
| Line 44: | Line 31: |
| ==== OSX ==== Freesurfer is supported on OSX El Capitan (10.11) and later, and we recommend using the brew package manager to install a few of the build dependencies: |
Then, to download the annex data, run the following from the top-level directory: |
| Line 49: | Line 34: |
| brew install cmake gcc5 qt5 | git fetch datasrc git-annex get . |
| Line 52: | Line 38: |
| The remaining dependencies can be built locally using the build_packages.sh freesurfer script, or they can just be downloaded as prebuilt packages (recommended). The following will create a `packages` directory containing a set of required freesurfer dependencies (built on OS X 10.11.6): | Further annex instructions can be found on the GitAnnex page. |
| Line 54: | Line 40: |
| {{{ curl https://surfer.nmr.mgh.harvard.edu/pub/data/fspackages/prebuilt/osx10.11-packages.tar.gz -o osx10.11-packages.tar.gz tar -xzvf osx10.11-packages.tar.gz }}} <<BR>> == Source == get source from github or fork -- get annex data -- <<BR>> |
|
| Line 71: | Line 42: |
| Freesurfer supports both in-source and out-of-source builds using CMake (although tests can only be run from an in-source build). To configure a simple in-source build tree, enter the top-level directory of the repository and run: | Freesurfer supports both in-source and out-of-source builds using CMake. To configure a simple in-source build tree, enter the top-level directory of the repository and run: |
| Line 77: | Line 48: |
| <!> External users not developing on the Martinos filesystem will get an error saying "". To resolve this, you must point cmake to the full path of the packages directory configured above with the following option: {{{ cmake . -DFS_PACKAGES_DIR="/path/to/packages" }}} This path can also be set in an `FS_PACKAGES_DIR` environment variable, so that it doesn't need to be supplied on the command line for every new configuration. |
'''NOTE:''' If you would like to completely re-configure a build, be sure to delete the `CMakeCache.txt` file from the top-level build directory. |
| Line 95: | Line 60: |
| ==== Packages ==== Users not developing on the Martinos filesystem will get an error indicating that external developers must provide a valid `FS_PACKAGES_DIR` path. To resolve this, you must point cmake to the full path of your packages directory (configured via the BuildRequirements instructions) with the following option: {{{ cmake . -DFS_PACKAGES_DIR="/path/to/packages" }}} This path can also be set in an `FS_PACKAGES_DIR` environment variable, so that it doesn't need to be supplied on the command line for every new configuration. |
|
| Line 97: | Line 72: |
| ==== Modules ==== | By default, the freesurfer build type is set to ''Release'', which configures `-O3` optimization with no debugging. To build with debugging turned on, configure the `CMAKE_BUILD_TYPE` variable to equal `Debug` or `RelWithDebInfo`, like so: |
| Line 99: | Line 74: |
| {{{ cmake . -DCMAKE_BUILD_TYPE="Debug" }}} |
|
| Line 100: | Line 78: |
| <<BR>> | |
| Line 103: | Line 80: |
| Once your build tree has been configured appropriately, freesurfer can be compiled with `make` and installed with `make install`. Additionally, unit and regression tests can be run with `make test` (previously `make check`) from individual subdirectories or from the top-level. The current 8-threaded build time is roughly 6 minutes. Single-threaded builds can take between 10 and 20 minutes. | Once your build tree has been configured appropriately, freesurfer can be compiled with `make` and installed with `make install`. Additionally, unit and regression tests can be run with `make test` from individual subdirectories or from the top-level build directory. |
FreeSurfer Build Guide
This page walks through the process of building the freesurfer source code. For an introduction to the repository and the development process, visit the DevelopersGuide.
Freesurfer depends on a variety of third-party tools, and the BuildRequirements page recommends the easiest ways to install these dependencies on your machine. External developers should make sure they correctly set up the freesurfer packages directory as instructed.
Source
Clone the freesurfer source code from github. If you're planning to commit changes to the main repository, make sure you clone from a forked repository instead and follow the recommended development cycle.
git clone git@github.com:freesurfer/freesurfer.git
Annex Data
The freesurfer repository contains many large binary files that can't be stored directly on github. The data can be retrieved from our server with git-annex, but the data source must first be setup as a remote repository. For those developing on the Martinos filesystem, cd into your repository and run:
git remote add datasrc file:///space/freesurfer/repo/annex.git
For those developing outside of Martinos, run:
git remote add datasrc https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/repo/annex.git
Then, to download the annex data, run the following from the top-level directory:
git fetch datasrc git-annex get .
Further annex instructions can be found on the GitAnnex page.
Configuration
Freesurfer supports both in-source and out-of-source builds using CMake. To configure a simple in-source build tree, enter the top-level directory of the repository and run:
cmake .
NOTE: If you would like to completely re-configure a build, be sure to delete the CMakeCache.txt file from the top-level build directory.
Install Path
By default, freesurfer will install to /usr/local/freesurfer, but the install path can be configured with:
cmake . -DCMAKE_INSTALL_PREFIX="/path/to/desired/install"
Alternatively, this path can be set in an FS_INSTALL_DIR environment variable to avoid having to specify it for every configuration.
Packages
Users not developing on the Martinos filesystem will get an error indicating that external developers must provide a valid FS_PACKAGES_DIR path. To resolve this, you must point cmake to the full path of your packages directory (configured via the BuildRequirements instructions) with the following option:
cmake . -DFS_PACKAGES_DIR="/path/to/packages"
This path can also be set in an FS_PACKAGES_DIR environment variable, so that it doesn't need to be supplied on the command line for every new configuration.
Optimization and Debugging
By default, the freesurfer build type is set to Release, which configures -O3 optimization with no debugging. To build with debugging turned on, configure the CMAKE_BUILD_TYPE variable to equal Debug or RelWithDebInfo, like so:
cmake . -DCMAKE_BUILD_TYPE="Debug"
Building
Once your build tree has been configured appropriately, freesurfer can be compiled with make and installed with make install. Additionally, unit and regression tests can be run with make test from individual subdirectories or from the top-level build directory.