             Setting OSX 10.8, 10.9, 10.10 for ESP-r
                      Jon W. Hand, ESRU
                       October 2016

INTRODUCTION

Apple computers can run ESP-r and are also great computers for
doing development work on ESP-r. OSX includes the scripting,
security and multi-tasking features of Linux/Unix computers
which ESP-r requires. For development work the compiler 'tool-chain' 
is almost identical to that on Linux (GCC and Make).

There are several tasks that are required before you can embark
on creating or using the virtual physics of ESP-r. Use the Apple 
Store to get the free XCode development environment as well as its command 
line utilities (see notes at the end of this document).

You will also need some additional libraries and development header 
files that are most easily setup via the MacPorts environment. 
These are discussed in subsequent sections.

Gfortran is not to be included in the XCode release and we recommend that
you source gcc g++ and gfortran (the -mp-4.9 or -mp-5 version) via 
MacPorts (see links below).  


FONTS

On OSX sometimes the GTK version of ESP-r will crash when attempting 
to display a pop-up message or display such as the wire-frame control 
proforma. This is usually resolved by re-freshing the font cache via 
the following command:
  sudo fc-cache -f -v

It might take several minutes to do this refresh of the font cache.

MACPORTS

The MacPorts environment (see useful links) is designed to assist
OSX users in installing open source software. It is possible to
find the GCC compiler collections (gcc g++ gfortran) for OSX 10.7
10.8, 10.9, 10.10 (10.11 being tested). MacPorts will place newly 
installed software in /opt/local (so that they do not clash with 
other software).

MacPorts package manages dependencies so the hassles of acquiring 
related software packages and/or libraries are reduced. With very
few commands the dependencies needed for ESP-r development and use
can be installed on your computer.

Go to the folder /opt/local. Check if a port exists use commands in the form:

  sudo bin/port search gcc5

And to install a package and its dependencies issue commands in the form:
  sudo bin/port install package_name

which will install that package and its dependencies. 

You will want to install the following port packages along with their
dependencies:
  sudo bin/port install gcc5, Imagemagick xfig gimp2

Note gimp2 tends not to completely install in OSX 10.11 but is
sufficient for building and running ESp-r. This combination of 
ports will result in g++-mp-5, gcc-mp-5 and gfortran-mp-5 in 
/opt/local/bin and the X11 and GTK libraries being located
in /opt/local/lib in addition to the X11 libraries generated by the initial
X11 install in /usr/X11R6 (/opt/X11 for OSX sierra).

The pure-text version needs none of the graphic libraries and will almost
always compile. The GTK version uses a utility called pkg-config to locate
libraries and will compile with few questions being asked.

COMPILING

By default OS X will place user accounts under the folder /Users. The
default location for ESP-r is /opt/esru. To create /opt/esru folder 
use a sudo command to create the new folder and to gain ownership of 
the new folder so that you can install ESP-r there.
  cd /opt
  sudo mkdir esru
  sudo chown your_login_name /opt/esru
  sudo chgrp staff /opt/esru

When compiling esp-r use Install script in the ESP-r source code
distribution. A typical command would be:

 ./Install_o1 -d /opt/esru --gcc4 --debug --compiler_version -mp-4.7

You can find out more about the source code compile process by giving
the command:

  ./Install --help

There are a few responses you need to provide during the Install process: 
a) if the Installer detects a machine type x86_64 say yes
b) if XML support is detected and you want to have XML output say yes
c) you are given a choice of GTK or X11 or pure-text interfaces
d) typically says yes to retaining debugging symbols
e) on first install and after merging in new databases or updates say
   yes to databases and training models
f) and if /opt/esru does not already have all of the distribution folders
   in place say yes to a request to create them. If the Install process
   cannot create the sub-folders you may have to update permissions.
g) lastly say yes to proceed with the installation.

The Install will echo the general progress as modules are built. 


SETTING UP YOUR ENVIRONMENT

To use ESP-r it is suggested that in your $HOME folder e.g. /Users/fred you
create a bin folder and a Models folder.  In bin place the scripts link_to
and link_to_bash from the distribution scripts folder. After building ESP-r into /opt/esru
issue the following commands:
  cd
  cd bin
  ./link_to /opt/esru/esp-r/bin

This will create links to the ESP-r executables. If your .profile or your .cshrc
environment files include $HOME/bin in the PATH definition when you login in
the next time you should be able to issue the command:
  which prj
and get back
  /Users/fred/bin/prj

If this does not work you may need to issue the following commands first:
  cd
  source .profile
  which prj

When creating new models a good habit is to start from your Models folder:
  cd
  cd Models
  prj

This will start up the ESP-r Project Manager and if you ask for a new model
it will be located in a subfolder of Models.

RADIANCE

The Radiance visual simulation suite R3.9 or R4.1 compiles ok on OSX 10.7,
10.8 or 10.9.  You also need to create a link named genrbox pointing
at genbox in /usr/local/bin (the typical location where Radiance is
compiled to). Normally it is not necessary to set the RAYPATH environment
variable if the Radiance library files are in /usr/local/lib/ray.

HELPER APPLICATIONS

ESP-r assumes that Linux-like operating systems will have installed the
ImageMagick package for displaying or capturing images as well as nedit
as a text editor and xfig to work with vector graphics.  These are available 
via MacPorts.


USEFUL LINKS

The newest compilers for OSX are not found in the XCode environment but in
external locations.  Here is a list of useful sites:

MacPorts site (http://www.macports.org) 
The MacPorts GCC 4.9 or 5.3 works well in OSX 10.9 and 10.10.

DEPENDENCIES

There are two versions of ESP-r which can be installed. The so-called
X11 version which uses the X11 graphics libraries and the GTK version 
which is based on the GTK+ graphics libraries. There are a few functions 
which are not available in the GTK version (e.g. click-on-bitmap). And 
ESP-r can also be invoked on the command line to run in a pure-text mode 
and there is an option to compile a version of ESP-r which is text based 
and has no dependencies on the X11 or GTK libraries.

ESP-r has a number of library dependencies for the X11 and GTK versions.
If you have all of the libraries that you need then the various modules 
of the ESP-r suite will run. If not all of them exist then you will get 
an error message with the name of the library or libraries that have not 
been found. 

If you are running the X11 version of esp-r there are only a few 
libraries that the executables will be looking for (the version 
numbers may be different on your machine):

otool -L ./clm
./clm:
        /usr/X11/lib/libX11.6.dylib (compatibility version 10.0.0, current version 10.0.0)
        /opt/local/lib/libgcc/libstdc++.6.dylib (compatibility version 7.0.0, current version 7.18.0)
        /usr/lib/libxslt.1.dylib (compatibility version 3.0.0, current version 3.24.0)
        /usr/lib/libxml2.2.dylib (compatibility version 10.0.0, current version 10.3.0)
        /opt/local/lib/libgcc/libgfortran.3.dylib (compatibility version 4.0.0, current version 4.0.0)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 159.1.0)
        /opt/local/lib/libgcc/libgcc_s.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /opt/local/lib/libgcc/libquadmath.0.dylib (compatibility version 1.0.0, current version 1.0.0)

These libraries will typically be installed with the X11 environment 
on Apple computers.

If you are using the GTK version of ESP-r then there are additional
libraries that are required. Many of these tend to be located in a /sw folder
structure which is maintained by the 'fink' development packages or
in /opt/lib if you are using MacPorts. 

% otool -L ./clm
./clm:
        /opt/local/lib/libgtk-x11-2.0.0.dylib (compatibility version 2401.0.0, current version 2401.22.0)
        /opt/local/lib/libgdk-x11-2.0.0.dylib (compatibility version 2401.0.0, current version 2401.22.0)
        /opt/local/lib/libpangocairo-1.0.0.dylib (compatibility version 3601.0.0, current version 3601.0.0)
        /opt/local/lib/libgio-2.0.0.dylib (compatibility version 3801.0.0, current version 3801.1.0)
        /opt/local/lib/libXrender.1.dylib (compatibility version 5.0.0, current version 5.0.0)
        /opt/local/lib/libXinerama.1.dylib (compatibility version 2.0.0, current version 2.0.0)
        /opt/local/lib/libXi.6.dylib (compatibility version 8.0.0, current version 8.0.0)
        /opt/local/lib/libXrandr.2.dylib (compatibility version 5.0.0, current version 5.0.0)
        /opt/local/lib/libXcursor.1.dylib (compatibility version 2.0.0, current version 2.2.0)
        /opt/local/lib/libXcomposite.1.dylib (compatibility version 2.0.0, current version 2.0.0)
        /opt/local/lib/libXdamage.1.dylib (compatibility version 3.0.0, current version 3.0.0)
        /opt/local/lib/libXfixes.3.dylib (compatibility version 5.0.0, current version 5.0.0)
        /opt/local/lib/libX11.6.dylib (compatibility version 10.0.0, current version 10.0.0)
        /opt/local/lib/libXext.6.dylib (compatibility version 11.0.0, current version 11.0.0)
        /opt/local/lib/libatk-1.0.0.dylib (compatibility version 21010.0.0, current version 21010.1.0)
        /opt/local/lib/libcairo.2.dylib (compatibility version 11203.0.0, current version 11203.16.0)
        /opt/local/lib/libgdk_pixbuf-2.0.0.dylib (compatibility version 3001.0.0, current version 3001.0.0)
        /opt/local/lib/libpangoft2-1.0.0.dylib (compatibility version 3601.0.0, current version 3601.0.0)
        /opt/local/lib/libpango-1.0.0.dylib (compatibility version 3601.0.0, current version 3601.0.0)
        /opt/local/lib/libgobject-2.0.0.dylib (compatibility version 3801.0.0, current version 3801.1.0)
        /opt/local/lib/libglib-2.0.0.dylib (compatibility version 3801.0.0, current version 3801.1.0)
        /opt/local/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.2.0)
        /opt/local/lib/libfontconfig.1.dylib (compatibility version 10.0.0, current version 10.0.0)
        /opt/local/lib/libfreetype.6.dylib (compatibility version 17.0.0, current version 17.2.0)
        /opt/local/lib/libgcc/libstdc++.6.dylib (compatibility version 7.0.0, current version 7.18.0)
        /opt/local/lib/libxslt.1.dylib (compatibility version 3.0.0, current version 3.28.0)
        /opt/local/lib/libxml2.2.dylib (compatibility version 12.0.0, current version 12.1.0)
        /opt/local/lib/libgcc/libgfortran.3.dylib (compatibility version 4.0.0, current version 4.0.0)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 159.1.0)
        /opt/local/lib/libgcc/libgcc_s.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /opt/local/lib/libgcc/libquadmath.0.dylib (compatibility version 1.0.0, current version 1.0.0)


Additional notes:

The developer kit XCode is only available via the Apple App Store and
comes with GCC. The command line tools needed for compiling ESP-r are an additional
install which is accessed via the Xcode -> Open developer tool -> More developer tools
options. 

With OSX 10.8 and 10.9 the X11 server is not longer included as a standard install,
you are directed to use XQuartz <xquartz.macosforge.org> with a Wiki at
<xquartz.macosforge.org/trac/wiki>.

OSX 10.10 has not yet been proven to work as a development
platform for ESP-r. However executables compiled with 10.8.5 will run
on 10.9 and 10.10 as long as XCode and the MacPorts gcc ddd gimp2 have been
installed. 


