Installing FSL on Apple Mac

Thanks to Robert Coghill for sponsoring the Apple port.

Contents:

Prerequisites
FSL install script
- Configuring your account for FSL usage using the install script
Checking the installation
Running the GUIs
Using Matlab Libraries
Further help
Advanced: Manual installation

Prerequisites

Before you install FSL you should first ensure that you have the X11 windowing system installed. To do this, look for the X11 application in the Utilities folder within the Applications folder (switch to the Finder and hit Apple-Shift-U to open the Utilities folder); by default versions of Mac OS X prior to 10.5 doesn't normally come with this installed (you'll almost certainly need X11 later for things other than FSL anyway).

If you do not have X11 then install it from the OS X Install CD. Insert the CD, open it in the Finder, scroll down to the Optional Installs.mpkg package and double click to launch the installer (in Mac OS X 10.5, the package is in the Optional Installs folder). Click through until the custom install window appears, expose the Applications section and select X11. Now click on 'Install'

FSL Install Script

An automated installer, fsl_installer.sh is available to carry out the installation (or application of a patch). In addition it will install FSLView into /Applications, automatically configure your environment to enable you to run FSL and (on Mac OS X 10.4) will configure the Apple Terminal application to allow the launching of X11 applications from it. Finally, if you use Matlab it will configure your startup.m file to allow you to use the FSL Matlab functions.

fsl_installer.sh - Version 1.6 09/02/2012

Running the installer

Once you have downloaded the installer, open a Terminal (look in the Utilities folder in Applications), change to the folder containing the downloaded file (for example if you downloaded to your Desktop):

cd ~/Desktop

(On Mac OS X 10.5, Safari defaults to downloading files into ~/Downloads)

and run it with:

sh fsl_installer.sh

Assuming that this folder also contains the FSL distribution tar file and you wish to install into /usr/local then just press Return when the installer asks a question, to accept the defaults. Be aware that you may need Administrator priviledges to install into certain folders on your computer - /usr/local being an example, the installer will ask for your password if necessary to allow this.

For more information on controlling the installer, run it with the -h option.

Configuring your account for FSL usage using the install script

In addition to installing the FSL programs, the install script is also capable of configuring your user account to enable you to run the FSL programs. If your user account was used to run the installer when installing the FSL programs, this will have already been done, but you may also want to configure additional accounts. To do this, log in as the user wishing to run FSL and execute the installer with the -e option, eg:

sh fsl_installer.sh -e

Checking the installation

Test that the environment and command line tools are set up correctly by doing the following:

Quit the Terminal program and start it again
Check that your environment is correct by typing:
```
echo $FSLDIR
```
This should display the name of the directory that you installed FSL in.
Check that your path is correct by typing:
```
flirt -version
```
which should display a line like:
```
FLIRT version 5.4.2
```
(although the version number might be different).

In general, to run the FSL tools from the command line (within a terminal) you need to enter the program name in lower case (e.g. bet). Typing a command on its own (without any arguments or options) gives you a help message for that command.

A more complete test of the FSL installation can be run at this point by using the testing and evaluation suite FEEDS.

Running the GUIs

Mac OS X 10.4

Once you have checked the environment and command line programs, as described above, then start X11 (click on it in the Utilities folder inside the Applications folder). All of the FSL GUIs should now work. To run a GUI version of a program you can either type its capitalised name with an additional '_gui' appended in the terminal (e.g. Bet_gui), or you can start the main FSL GUI by just typing fsl.

Mac OS X 10.5

There is no need to launch X11.app before starting any of the FSL GUIs, the X11 system automatically launches. To run a GUI version of a program you can either type its capitalised name with an additional '_gui' appended in the terminal (e.g. Bet_gui), or you can start the main FSL GUI by just typing fsl.

If you have upgraded from 10.4, then you may have a .bash_profile (or .tcshrc or .cshrc) that breaks this behaviour. If you installed using the fsl_installer.sh script then download the current version, fsl_installer.sh, and re-run using the -e option from a terminal:

cd ~/Downloads
sh fsl_installer.sh -e

assuming that your web browser downloads to the folder ~/Downloads. If you have manually added this to your shell setup file then look for a line that changes/sets the DISPLAY environment variable and remove it. New shells will then behave as expected.

Also note that at this time, Apple's X11.app as shipped, has a large number of bugs and performance issues. Until such time as an offical release corrects these problems, you may see significant improvements by installing the testing release available at http://www.x.org/wiki/XDarwin (follow the instructions for a Binary installation).

Using Matlab libraries

FSL ships with several Matlab scripts for loading Analyze files. These libraries are dependant on FSL environment variables which aren't set in the Mac OS X Desktop environment, so won't run in a Matlab session started from the /Applications/MATLAB.app launcher. There are two options:

Run Matlab from a correctly configured Terminal (assuming Matlab 7.4 - adjust as appropriate for your version)
```
/Applications/MATLAB74/bin/matlab
```
or
Configure the FSL environment variable in your ~/matlab/startup.m file (create it if it doesn't already exist) - add the following (assuming FSL installed in /usr/local):
```
setenv( 'FSLDIR', '/usr/local/fsl');
fsldir = getenv('FSLDIR');
fsldirmpath = sprintf('%s/etc/matlab',fsldir);
path(path, fsldirmpath);
clear fsldir fsldirmpath;
```

Further help

If any problems occur when installing or running the FSL tools, please consult the FSL FAQ. This also contains instructions on how to join and use the FSL email list to ask specific questions which are not covered in the FAQ.

Manual Installation

Verify the download
- Visit our checksums page to download the MD5 sum file that matches the .tar.gz package you have downloaded. Make sure that the .md5 file is in the same directory as the downloaded FSL distribution file.
- Open up a Terminal (you can find this application in Utilities folder inside the Applications folder).
- In the terminal, change to the directory where you downloaded the FSL distribution, e.g.
```
cd ~/Downloads
```
- Check the file with
```
fsl=`ls -1 fsl-4.*-macosx.tar.gz`; md5 $fsl | diff -q - $fsl.md5
```
  NB ` is on the key to the left of Z on the UK Mac keyboard, or to the left of 1 on the US Mac keyboard
- If there is a problem with the download then you will receive a message like:
```
Files .... and .... differ
```
Unpack the FSL distribution
- Open up a Terminal (you can find this application in Utilities folder inside the Applications folder).
- In the terminal, change to the directory where you want FSL installed, e.g.
```
cd /usr/local
```
- Unpack the fsl download file - for example, if you downloaded it onto your Downloads folder,
```
tar -zxvf ~/Downloads/fsl-*-macosx.tar.gz
```
  (omit the z in the -zxvf if your computer has already uncompressed the tarfile for you). This will create a directory called fsl in the current directory which will contain all the required files for FSL and FSLView. Note that you might need to add sudo to the start of the tar command if you don't automatically have the right to create files in /usr/local.
Install the applications
- To get a clickable application icon FSLView, open a file browser in the top-level fsl directory, e.g.
```
open /usr/local/fsl
```
  and drag the fslview.app directory into your Applications folder or your Desktop.
- Find out which shell you are running. In a terminal, type:
```
help
```
  the output will be either a list of commands, in which case you are using the bash shell, or an error saying "command not found" or similar message, in which case you are using the tcsh or csh shell.

Set up your user environment.

If you are using the bash shell (the default)

In a running terminal type:
```
cd 
touch .bash_profile
open -a TextEdit .bash_profile
```
This will bring up a TextEdit window
Select Make Plain Text from the Format menu if it is available (if only Make Rich Text is there then do nothing as it is already in plain text mode)

In the window type the following lines at the end of the document (or better still, use copy and paste to do this):

FSLDIR=/usr/local/fsl
. ${FSLDIR}/etc/fslconf/fsl.sh
PATH=${FSLDIR}/bin:${PATH}
export FSLDIR PATH

Note that the second line starts with a dot (i.e. full stop or period), then a space, then ${FSLDIR}/etc/fslconf/fsl.sh - the dot and space are very important!

For Mac OS X 10.4 and earlier (NOT Mac OS X 10.5), also include the following:

if [ -z "$DISPLAY" -a "X$TERM_PROGRAM" = "XApple_Terminal" ]; then
  X11_FOLDER=/tmp/.X11-unix
  currentUser=`id -u`
  userX11folder=`find $X11_FOLDER -name 'X*' -user $currentUser -print 2>&1 | tail -n 1`
  if [ -n "$userX11folder" ]; then
    displaynumber=`basename ${userX11folder} | grep -o '[[:digit:]]\+'`
    if [ -n "$displaynumber" ]; then
      DISPLAY=localhost:${displaynumber}
      export DISPLAY
    else
      echo "Warning: DISPLAY not configured as X11 is not running"
    fi
  else
    echo "Warning: DISPLAY not configured as X11 is not running"
  fi
fi

Change the line FSLDIR=/usr/local/fsl and replace /usr/local/fsl with the directory name of the place where you installed FSL.
Save the file and exit TextEdit

If you are using the tcsh or the csh shell

In a running terminal type:
```
cd 
touch .cshrc
open -a TextEdit .cshrc
```
This will bring up a TextEdit window
Select Make Plain Text from the Format menu if it is available (if only Make Rich Text is there then do nothing as it is already in plain text mode)

In the window copy and paste the following in at the end of the document:

setenv FSLDIR /usr/local/fsl
source ${FSLDIR}/etc/fslconf/fsl.csh
setenv PATH ${FSLDIR}/bin:${PATH}

For Mac OS X 10.4 and earlier (NOT Mac OS X 10.5), also include the following:

if ( $?TERM_PROGRAM ) then
 if ( "X$TERM_PROGRAM" == "XApple_Terminal" ) then; if ( ! $?DISPLAY ) then
      set X11_FOLDER=/tmp/.X11-unix; set currentUser=`id -u`; set userX11folder=`find $X11_FOLDER -name 'X*' -user $currentUser -print | tail -n 1`
      if ( "X$userX11folder" != "X" ) then
        set displaynumber=`basename ${userX11folder} | grep -o '[[:digit:]]\+'`
        if ( "X$displaynumber" != "X" ) then
          setenv DISPLAY localhost:${displaynumber}
        else; echo "Warning: DISPLAY not configured as X11 is not running"
        endif
      else
        echo "Warning: DISPLAY not configured as X11 is not running"
      endif
    endif 
  endif
endif

Change the line setenv FSLDIR /usr/local/fsl and replace /usr/local/fsl with the directory name of the place where you installed FSL.