Installation

Important Note for macOS users: macOS machines require the installation of XQuartz 2.7.6.

Installing XQuartz

To see what version of macOS you have, click Apple -> About This Mac. You should see something similar to the image below:

To see what version of XQuartz you have, click Applications -> Utilities -> XQuartz. Then X11 -> About X11

If necessary, download the XQuartz installation package and double click it to install.

XQuartz 2.7.5 (macOS versions 10.6 - 10.9)
XQuartz 2.7.6 (macOS versions 10.10 and higher)

Installing FreeSurfer

Download the FreeSurfer installation package from this page. Double click the dmg then double click the freesurfer-Darwin-full.pkg to launch the installation wizard:

If you get this error:

Then you need to adjust your security settings to allow applications from 3rd party developers to be installed. To do this go to Apple -> System Preferences -> Security & Privacy -> General. Click the lock on the bottom left to make changes and under Allow applications downloaded from: select Anywhere.

After the package integrity has been verified, the introductory screen will appear. Click on Continue:

Next is the Read Me window. Click on Continue:

Next is the Software License Agreement window. Click on Continue:

Next is the Destination Select window. Click Change Install Location... to change the default installation disk and folder (/Applications/freesurfer). Or click Install to go with default:

You may need to enter you password. The installation process will begin to write files and will take a few minutes to complete.

Setup and Configuration

To begin using freesurfer, open a terminal window. The Terminal application is found under Applications -> Utilities -> Terminal:

Type the following lines in the terminal window to source the freesurfer environment:

export FREESURFER_HOME=/Applications/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

After you source freesurfer you should see some output similar to the window below:

If you use freesurfer frequently and want to avoid typing the above lines of code every time you open a terminal window, you can create a file called .profile in your home directory which contains those two line. This will cause the terminal window to automatically source freesurfer every time it is opened.

At this point you are ready to begin using the freesurfer software. If you haven't done so already, obtain a license, and copy the license.txt file into your $FREESURFER_HOME (Applications/freesurfer) directory.

Testing Freesurfer

See the this page for some example commands to test that FreeSurfer is installed and running properly.

For newer Mac OS Systems

If you receive the following error when running the test_commands.sh.15 script:

+ cd /users/hippo/lcn/tutorial_data/tutorial_data_20190918_1558/buckner_data/tutorial_subjs/group_analysis_tutorial
+ mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh
dyld: lazy symbol binding failed: Symbol not found: ___emutls_get_address
  Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib
  Expected in: /usr/lib/libSystem.B.dylib

dyld: Symbol not found: ___emutls_get_address
  Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib
  Expected in: /usr/lib/libSystem.B.dylib

./test_commands.sh.15: line 368: 87124 Abort trap: 6           mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh

Then, you need to install a Freeview patch to have this work with your Mac OS version. Download the patch (~33 MB) from /autofs/cluster/pubftp/dist/freesurfer/6.0.0-patch/Freeview_6_0_0_MacOS_patch.zip follow the following instructions:

1)To download the patch, follow instructions on using the ftp file exchange from this wiki page.

2) Remove your existing Freeview.app application bundle by sending it to the trash (and then emptying the trash).You can also do this from the terminal by cd'ing to the top-level ./freesurfer subdirectory and then doing

rm -rf Freeview.app

3) Copy the new Freeview.app.zip to where your old Freeview.app was located and uncompress it (so it becomes the replacement Freeview.app in your current FreeSurfer installation).

4) Remove ./freesurfer/lib/gcc/lib/libgomp.1.dylib from your existing freesurfer installation.

5) Copy the ./freesurfer/lib/gcc/lib/libgomp.1.dylib from the patch archive to /freesurfer/lib/gcc/lib in your current freesurfer installtion.

6) Try running the Freeview.app and loading a volume with it.

-  ⇤ ← Revision 30 as of 2014-10-30 11:03:06 → 
  Size: 5267
  Editor: ZekeKaufman
  Comment:
+   ← Revision 77 as of 2020-03-04 12:46:10 → ⇥
  Size: 6437
  Editor: LeahMorgan
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 3:
-= FreeSurfer Mac OS X Installation and Setup =
'''Before proceeding:''' The Max OS X machine must have [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.5.dmg|XQuartz 2.7.5]] installed before you can run !FreeSurfer (new versions of XQuartz break some of the GUIs). To check if you already have [[http://xquartz.macosforge.org/landing|XQuartz]], open a Finder window and look for it under '''Applications -> Utilities -> XQuartz'''. If it is not there, please download and install [[http://xquartz.macosforge.org/landing|XQuartz]] before proceeding with the !FreeSurfer installation. *NOTE:* Major upgrades to you Mac system (e.g. from Mountain Lion to Mavericks) will require a reinstallation of [[http://xquartz.macosforge.org/landing|XQuartz]].
+'''Index''' <<TableOfContents>>
-Line 6:
+Line 5:
-{{attachment:XQuartz_screencapture.png}}
+= Installation =
'''''Important Note for macOS users:''' macOS machines require the installation of [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.6.dmg|XQuartz 2.7.6]].''
----
-Line 8:
+Line 9:
-Once the '''dmg''' installation file has been downloaded, double click on it to expand the package:
+=== Installing XQuartz ===
-Line 10:
+Line 11:
-{{attachment:install-4mpkg.jpg}}
 Line 12:
-Double click on the '''mpkg''' to launch the installation wizard. If you get this error:
+To see what version of macOS you have, click '''Apple -> About This Mac'''. You should see something similar to the image below:

{{attachment:macversion.png}}

To see what version of XQuartz you have, click '''Applications -> Utilities -> XQuartz'''. Then '''X11 -> About X11'''


{{attachment:xqfinder.png}} 
{{attachment:xqversion.png}}


If necessary, download the XQuartz installation package and double click it to install.

 * [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.5.dmg|XQuartz 2.7.5]] (macOS versions 10.6 - 10.9)
 * [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.6.dmg|XQuartz 2.7.6]] (macOS versions 10.10 and higher)

----

=== Installing FreeSurfer ===

Download the !FreeSurfer installation package from [[DownloadAndInstall|this page]]. Double click the dmg then double click the '''freesurfer-Darwin-full.pkg''' to launch the installation wizard:

{{attachment:install-5mpkg.png}}

If you get this error:
-Line 16:
+Line 40:
-Then you need to adjust your security settings to allow applications from 3rd party developers to be installed. To do this go to '''System Preferences -> Security & Privacy -> General'''. Click the lock on the bottom left to make changes and under '''Allow applications downloaded from:''' select '''Anywhere'''.
+Then you need to adjust your security settings to allow applications from 3rd party developers to be installed. To do this go to '''Apple -> System Preferences -> Security & Privacy -> General'''. Click the lock on the bottom left to make changes and under '''Allow applications downloaded from:''' select '''Anywhere'''.
-Line 21:
+Line 45:
-Line 24:
+Line 47:
-After the package integrity has been verified, the introductory screen will appear.
+After the package integrity has been verified, the introductory screen will appear. Click on '''Continue''':
-Line 28:
+Line 51:
-Click on '''Continue''':
+Next is the Read Me window. Click on '''Continue''':
-Line 30:
+Line 53:
-{{attachment:install-6readme.jpg}}
+{{attachment:readme1.png}}
-Line 32:
+Line 55:
-If you're not sure how to follow the instructions in the Read Me window, don't worry - we'll come back to them. To set up your computer to automatically load !FreeSurfer when a terminal window is opened, add the following lines to the '''.profile''' file in your home directory:
+Next is the Software License Agreement window. Click on '''Continue''':

{{attachment:SLA.png}}

Next is the Destination Select window. Click '''Change Install Location...''' to change the default installation disk and folder (/Applications/freesurfer). Or click '''Install''' to go with default:

{{attachment:install_location.png}}

You may need to enter you password. The installation process will begin to write files and will take a few minutes to complete.

{{attachment:successful.png}}

-----

= Setup and Configuration =

To begin using freesurfer, open a terminal window. The Terminal application is found under '''Applications -> Utilities -> Terminal''':

{{attachment:terminal.png}}

Type the following lines in the terminal window to source the freesurfer environment:
-Line 37:
+Line 80:
 }}}
-Line 39:
+Line 82:
-If you don't already have a '''.profile''' file in your home directory, you can go ahead and create one using pico or some other text editor:
+After you source freesurfer you should see some output similar to the window below:

{{attachment:source_freesurfer.png}}

If you use freesurfer frequently and want to avoid typing the above lines of code every time you open a terminal window, you can create a file called '''.profile''' in your home directory which contains those two line. This will cause the terminal window to automatically source freesurfer every time it is opened. 

At this point you are ready to begin using the freesurfer software. If you haven't done so already, [[https://surfer.nmr.mgh.harvard.edu/registration.html|obtain a license]], and copy the license.txt file into your $FREESURFER_HOME (Applications/freesurfer) directory.

-----

= Testing Freesurfer =

See the [[DownloadAndInstall#TestyourFreeSurferInstallation|this page]] for some example commands to test that !FreeSurfer is installed and running properly.

= For newer Mac OS Systems =

If you receive the following error when running the test_commands.sh.15 script:
-Line 42:
+Line 101:
-pico .profile
++ cd /users/hippo/lcn/tutorial_data/tutorial_data_20190918_1558/buckner_data/tutorial_subjs/group_analysis_tutorial
+ mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh
dyld: lazy symbol binding failed: Symbol not found: ___emutls_get_address
  Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib
  Expected in: /usr/lib/libSystem.B.dylib

dyld: Symbol not found: ___emutls_get_address
  Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib
  Expected in: /usr/lib/libSystem.B.dylib

./test_commands.sh.15: line 368: 87124 Abort trap: 6           mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh
-Line 45:
+Line 114:
-Copy and paste the two lines from the previous box into the blank screen that appears. After that, type Ctrl+x to exit. Then type 'y' and then hit enter to save your changes.
+Then, you need to install a Freeview patch to have this work with your Mac OS version. Download the patch (~33 MB) from /autofs/cluster/pubftp/dist/freesurfer/6.0.0-patch/Freeview_6_0_0_MacOS_patch.zip follow the following instructions:

1)To download the patch, follow instructions on using the ftp file exchange from [[https://surfer.nmr.mgh.harvard.edu/fswiki/FtpFileExchange|this]] wiki page.

2) Remove your existing Freeview.app application bundle by sending it to the trash (and then emptying the trash).You can also do this from the terminal by cd'ing to the top-level ./freesurfer subdirectory and then doing
{{{
rm -rf Freeview.app
}}}

3) Copy the new Freeview.app.zip to where your old Freeview.app was located and uncompress it (so it becomes the replacement Freeview.app in your current FreeSurfer installation).

4) Remove ./freesurfer/lib/gcc/lib/libgomp.1.dylib from your existing freesurfer installation.

5) Copy the ./freesurfer/lib/gcc/lib/libgomp.1.dylib from the patch archive to /freesurfer/lib/gcc/lib in your current freesurfer installtion.

6) Try running the Freeview.app and loading a volume with it.
-Line 48:
+Line 132:
-On the installation wizard, click on '''Continue''' and read the end user license agreement, scrolling down using the bar along the right side of the window. <<BR>>
Click '''Continue'''.

## attachment:install-7license.jpg
## attachment:install-8licenseclick.jpg

After you agree to the license agreement, you can select where to install the software. Highlight the hard drive where you want to install it (if not already highlighted). To change the directory where it is installed (Applications is the default location), hit the '''Choose''' button.

{{attachment:install-9selectdestination.jpg}}
-Line 59:
+Line 134:
-## attachment:install-10destinationselected.jpg
-Line 61:
+Line 135:
-Click '''Continue'''.
-Line 63:
+Line 136:
-{{attachment:install-11easyinstall.jpg}}
+## Lastly, if you intend to run recon-all (the processing script which can run for 24 hours) on your mac, we recommend setting your Power Adapter Energy Settings to 'Never' sleep, otherwise recon-all will only run when you are logged-in. This is done under '''System Preferences -> Energy Saver'''.
-Line 65:
+Line 138:
-## To customize the installation, click on '''Customize''' and this screen will appear, allowing selection of packages to install:
+## {{attachment:no_sleep.png}}
-Line 67:
+Line 140:
-## attachment:install-12custominstall.jpg

## If not all of the packages are selectable, check in the directory /Library/Receipts for directories matching the package names. The operating system will compare the ## new installation against any old installations, and will prevent upgrades if the version of the package being installed is older than the one currently installed. Remove ## the receipt directory to reinstall a new version of the desired software packages and restart the installer by double clicking on the mpkg.

Click on '''Install''' and the package will begin to be installed at the location you chose. The installer may then optimize the hard drive for performance.

## attachment:install-13procfsbins.jpg
## attachment:install-14procfssupport.jpg
## attachment:install-15procdata.jpg
## attachment:install-16procminc.jpg
## attachment:install-17procfullinst.jpg

## attachment:install-18optimisinghd.jpg

Once the optimization is finished, the installation process should be successful:

{{attachment:install-19success.jpg}}

If you encounter errors during the installation, while still in the Installer, and Installer is still the primary application, click the '''Window -> Installer Log''' menu item to show the error log to see why installation failed.  

Otherwise, click on '''Close''' to exit the installer. 

Lastly, if you intend to run recon-all (the processing script which can run for 24 hours) on your mac, we recommend setting your Power Adapter Energy Settings to 'Never' sleep, otherwise recon-all will only run when you are logged-in. This is done under '''System Preferences -> Energy Saver'''.

{{attachment:no_sleep.png}}

If you came from the Quick Install page, return to that [[QuickInstall|here]].<<BR>>
Otherwise, setup and configuration of the environment is described [[SetupConfiguration_Mac|next.]]
+## If you came from the Quick Install page, return to that [[QuickInstall|here]].<<BR>>
## Otherwise, setup and configuration of the environment is described [[SetupConfiguration_Mac|next.]]