Install EGSnrc on OS X Yosemite

Overview

Installing EGSnrc on OS X involves 3 steps:

1. Install prerequisite software
2. Download EGSnrc
3. Configure EGSnrc

1. Install prerequisite software

Before installing EGSnrc on OS X, ensure the software listed below is available on your system. By default, Fortran, C and C++ Compilers are not installed on OS X. The following instructions are valid for a pristine copy of OS X. If you already have development tools installed, such as Xcode for example, you should adjust the installation procedure to prevent interfering with your existing software build chain. To use EGSnrc you need:

1. a Fortran compiler (preferably gfortran)
2. a C compiler (preferably gcc)
3. a C++ compiler (preferably g++)
4. the GNU make utility
5. optional: the Tcl/Tk interpreter and widget toolkit, version 8.0 or later
6. optional: the Grace plotting tool (providing the xmgrace command), version 5.0 or later
7. optional: the Qt4 development tools (to compile the Qt graphical user interfaces)

Compilers and GNU make utility

You may use any working Fortran, C and C++ compilers on your system. We develop and use EGSnrc with the GNU compilers gfortran, gcc and g++, so these are recommended. If you use other compilers, you might have to adjust compilation options in the configuration stage in order for EGSnrc to work as expected. EGSnrc also relies on a make tool, which controls and automates the software building process: most EGSnrc applications are built by issuing the make command in the appropriate directory. There are various implementations of make, but EGSnrc relies on features of the GNU implementation.

Open the Terminal application in OS X and issue the following command to install gcc, g++, and the GNU make utlity:

xcode-select --install

The GNU Fortran compiler gfortran is not available within OS X, hence you need to download gfortran-5.1-bin.tar.gz from http://hpc.sourceforge.net/. Open the Terminal application, go to the directory where you downloaded the file and extrac the pre-compiled binary files with the -C /. flag to install under /usr/local/:

cd /path/to/download/directory/
sudo tar -xzvf gfortran-5.1-bin.tar.gz -C /.

To check that you have working Fortran, C, C++ compilers and the GNU make tool, issue the following commands (or equivalent ones if you are using other compilers) in the Terminal application:

gfortran --version          # should report your Fortran compiler version
gcc --version               # should report your C compiler version
g++ --version               # should report your C++ compiler version
make --version              # should report "GNU Make" on first line

Note that by default, some parts of EGSnrc require a compiler that supports standard C++11 (g++ option -std=c++11), and will soon require C++14 (g++ option -std=c++14). If you have an older compiler that does not recognize this option, please adjust or remove it from the list of proposed flags during the EGSnrc configuration.

Tcl/Tk

While Tcl/Tk is not essential to run EGSnrc simulations, it proves useful if you want to use EGSnrc graphical user interfaces. Conveniently, Tcl/Tk is included in macOS, which you can confirm with the following command in the Terminal application:

echo 'puts [info patchlevel]; exit 0' | wish    # should report version 8.0 or newer

Grace

Grace proves useful if you want to display data plots generated by EGSnrc applications. The easiest way to get the Grace plotting tool on macOS is to install QtGrace, which is a port of the original Grace software to the Qt toolkit and which can run under Linux, macOS and Windows. You can download QtGrace from http://sourceforge.net/projects/qtgrace/.

If you prefer to use the native X11 implementation of Grace (the same that is available on Linux), you can use a third-party package manager such as Homebrew or MacPorts to install the necessary components. For example, to install grace with Homebrew, enter the following commands in the Terminal application (supplying your password when required):

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install Caskroom/cask/xquartz
brew install homebrew/x11/grace

2. Download EGSnrc

To use the EGSnrc toolkit you must copy the entire EGSnrc directory tree to your computer. All the project files are grouped in a single top-level EGSnrc directory which you can put just about anywhere on your system (preferably under your home directory for a single-user installation) as long as the path contains no blank space or '@' character. We recommend that you use git to clone the EGSnrc repository, but alternatively you may download a compressed image of the EGSnrc directory.

Option 1: Clone the git repository

1. Open the Terminal application
2. Check that git is available on your system: git --version
3. Change directory to the desired install location: cd path/to/your/install/location
4. Clone the EGSnrc repository: git clone https://github.com/nrc-cnrc/EGSnrc.git

Option 2: Download a zipped archive

1. Download the compressed image EGSnrc-master.zip
2. Move the EGSnrc-master.zip file to the desired install location
3. Uncompress the archive using the unzip command-line tool, or your favorite utility
4. If you want, you can rename the inflated EGSnrc-master directory to EGSnrc

3. Configure EGSnrc

Once you have the EGSnrc source code on your computer, you must configure EGSnrc for your particular operating system and software environment, using a configuration shell script that prompts you for configuration options on the command-line.

1. Open the Terminal application
2. For a fresh install, clear existing EGSnrc environment variables with the command:
   export HEN_HOUSE="" EGS_HOME="" EGS_CONFIG=""
3. Go to your EGSnrc directory: cd path/to/EGSnrc/directory
4. Launch the configuration script: ./HEN_HOUSE/scripts/configure
5. Answer prompts and follow instructions rigorously
6. In your ~/.profile file, insert commands to define $EGS_HOME, $EGS_CONFIG and source EGSnrc additions, as prescribed at the end of the user configuration script
7. Download EGSnrc-guis-macos.zip, which provides pre-compiled EGSnrc graphical user interfaces, from the latest release