
        Steps to create or use the ESP-r installers on OSX
                             November 2013

Pre-compiled versions of ESP-r on OSX are usually distributed in
the form of a compressed tar archive of a newly compiled and working
ESP-r distribution. There are two interface to ESP-r. The
so-called X11 version is the legacy version and the GTK version
is an almost complete port of ESP-r using the GTK library. There
are a few functions which are not available in the GTK version
(e.g. click-on-bitmap).  The GTK version also has library
dependencies which are not required with the X11 version.

Compiling ESP-r from source

First compile a standard version of esp-r (X11 version) in the standard
location which on OSX should be /opt/esru. As /opt is a protected area 
before you issue the Install command give the following commands:
  cd /opt
  sudo mkdir esru
  sudo chown your_login_name /opt/esru
  sudo chgrp staff /opt/esru

Return to where the ESP-r source tree, in the src folder is an Install
script, to build ESP-r issue a command such as:

  ./Install -d /opt/esru --gcc4 --debug --compiler_version -mp-4.6

The --compiler_version above is followed by the -mp-4.6 if you used
MacPorts to install the gcc g++ and gfortran compilers series 4.6.
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. 

Second, there may be hidden folders related to the version control system
called subversion which is used by the ESP-r development community. There
is no need for these hidden folders in a distribution. To clean these up go 
to /opt/esru and issue the following command:

  find . -name .svn -print >which_svn
  rm -rf `cat which_svn`

You can have both an X11 and GTK version if the executables are located
in separate folders e.g. /opt/esru/esp-r/binX11 and /opt/esru/esp-r/binGTK.
The Install will have created /opt/esru/esp-r/bin. If you create alternative
folders you can copy the executables from /opt/esru/esp-r/bin to the
alternative folder.

If you are compiling the GTK version you will need the C
header files and libraries related to GTK before you can
compile this version of ESP-r. Look in the document about setting
up OSX for ESP-r development for more information about this.

Before compiling a second interface type clear the source (via a make clean) and 
compile the alternative interface. You can say no to the databases and example
models as these already exist.  When the Install process has finished check and
remove the subversion .svn folders from the /opt/esru folders.


Creating the compressed tar files

Follow the instructions above to compile the X11 version of ESP-r to 
the /opt/esru folder structure. Be sure to remove the .svn folders as 
described above. And try running several of the new ESP-r executables.  
To ensure the correct path is included in the tar 
file create the tar file (alter the v12.0 to match the actual version
of ESP-r) via the following commands:

  cd /
  sudo tar cf esp-r_x12_0_osx_in_opt.tar opt/esru
  sudo gzip -9 esp-r_x12_0_osx_in_opt.tar

Dependencies

ESP-r has a number of library dependencies depending 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
bash-3.2$ 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 and /opt/local/lib folders 
on Apple computers.

if you are using the GTK version of ESP-r then there are more dependendies
Many of these tend to be located in a /sw folder if you are using 'fink' or
/opt/local if you are using MacPorts.

% otool -L ./clm
./clm:
        /sw/lib/libgtk-x11-2.0.0.dylib (compatibility version 401.0.0, current version 401.9.0)
        /sw/lib/libgdk-x11-2.0.0.dylib (compatibility version 401.0.0, current version 401.9.0)
        /usr/X11R6/lib/libXrandr.2.dylib (compatibility version 2.0.0, current version 2.0.0)
        /usr/X11R6/lib/libXinerama.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /usr/X11R6/lib/libXext.6.dylib (compatibility version 6.4.0, current version 6.4.0)
        /usr/X11R6/lib/libXft.2.dylib (compatibility version 2.1.0, current version 2.1.0)
        /usr/X11R6/lib/libfreetype.6.dylib (compatibility version 6.3.0, current version 6.3.0)
        /usr/X11R6/lib/libXrender.1.dylib (compatibility version 1.2.0, current version 1.2.0)
        /usr/X11R6/lib/libfontconfig.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /usr/X11R6/lib/libX11.6.dylib (compatibility version 6.2.0, current version 6.2.0)
        /usr/X11R6/lib/libXcursor.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /sw/lib/libatk-1.0.0.dylib (compatibility version 601.0.0, current version 601.1.0)
        /sw/lib/libgdk_pixbuf-2.0.0.dylib (compatibility version 401.0.0, current version 401.9.0)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 88.1.11)
        /sw/lib/libpangoxft-1.0.0.dylib (compatibility version 601.0.0, current version 601.0.0)
        /sw/lib/libpangox-1.0.0.dylib (compatibility version 601.0.0, current version 601.0.0)
        /sw/lib/libpango-1.0.0.dylib (compatibility version 601.0.0, current version 601.0.0)
        /sw/lib/libgobject-2.0.0.dylib (compatibility version 601.0.0, current version 601.6.0)
        /sw/lib/libgmodule-2.0.0.dylib (compatibility version 601.0.0, current version 601.6.0)
        /sw/lib/libglib-2.0.0.dylib (compatibility version 601.0.0, current version 601.6.0)
        /sw/lib/libintl.1.dylib (compatibility version 2.0.0, current version 2.1.0)
        /sw/lib/libiconv.2.dylib (compatibility version 6.0.0, current version 6.0.0)
        /usr/lib/libmx.A.dylib (compatibility version 1.0.0, current version 93.0.0)

If the compressed archive is to be used on another OSX computer the gfortran run time libraries (for Intel) may be needed. These need to be placed in /usr/local/lib if the machine does not have the full GNU GCC compiler tool set.


Using/testing the compressed archive

The extraction process will place an ESP-r distribution in the folders:

  /opt/esru/esp-r/
    bin
	climate
	databases
	manual
	training
	validation

The first step is to prepare a folder to install the ESP-r distribution. The
usual location is /opt/esru.  If you already have an /opt folder then skip
to `section two`. Because /opt is a protected folder it prevents normal users
from writing files in it and that ensures that the `corporate` databases ESP-r
uses cannot be casually modified. Installing an application in /opt requires
that you use the `sudo` command to preface your commands.

ESP-r requires an X11 environment to be installed on your OSX box. See the 
separate instructions for this.  The finder will tend to hide the .gz portion
of the archive and it may attempt to unpack it incorrectly so use the terminal
or an X11 command window to work with an ESP-r distribution archive.

There is some information you will need. Start up either a terminal or and X11 
window. Issue the following commands

  cd
  ls -l

You are looking for your user name and your group name. E.g.

drwxr-xr-x    60 jon  jon       2040 Jul 15 06:49 testing

the first jon is the user name and the second instance is the 
name of the group. In some cases the second instance might 
be staff or users.

To determine if it is necessary to create the /opt folder start
up either a terminal or and X11 terminal. In the terminal
give the following command:

  ls -l /

in the listing given look for the following line:

drwxr-xr-x    15 root  admin      510 Aug 31 12:38 opt

If you find this entry then there exists a /opt folder and
you should skip down to Section Two.

To create a new /opt folder give the following commands. Lets
assume that your login name is fred and your group is staff.

  cd /
  sudo mkdir opt
  sudo chmod a+x opt
  sudo chmod a+r opt
  cd /opt
  sudo mkdir esru
  sudo chown fred esru
  sudo chgrp staff esru
  sudo chmod a+x esru
  sudo chmod a+r esru
  sudo chmod u+w esru


Machines with an existing /opt folder

This section assumes that a /opt folder exists. As a standard
user you probably do not have permission to write new files and
folders in /opt so you will have to use the 'sudo' command.
The following commands create a folder /opt/esru

  cd /opt
  sudo mkdir esru
  sudo chown fred esru
  sudo chgrp staff esru
  sudo chmod a+x esru
  sudo chmod a+r esru
  sudo chmod u+w esru

Copy the the_file_name_tar.gz file (that you downloaded or was created in in 
the procedures above) to the / folder via the following commands 
(depending on which version of ESP-r you want:

 cd to_the_folder_with_the_tar.gz file
 sudo cp the_file_name.tar.gz /
 cd /
 sudo tar xfz the_file_name.tar.gz

This will create the ESP-r folder structure within /opt/esru
but it will be owned by the root user.  You now need to
alter the ownership of the /opt/esru folder structure.

Now lets make sure that everything in the folder /opt/esru
is available to be owned
  cd /opt/esru

  ls -l

And you should see
total 0
drwxr-xr-x   14 fred  staff  476 Aug 27 02:46 esp-r

If you see that the user is root and the user is admin
then we need to alter this via the following commands:

  cd /opt
  sudo chown -R fred esru
  sudo chgrp -R staff esru


Adapting your environment

You will need to set an environment variable PATH so that
the folder /opt/esru/esp-r/bin is known. Go back to your
home folder and see if there is a .cshrc or a .profile file.

  cd
  ls -al

Some users of ESP-r prefer to use the "C" shell. And the closest
thing on OSX is the tcsh interpreter (available within the MacPorts
package management system). The entry in the .cshrc file in
your home folder might look something like:

set path = ( $path /usr/local/bin /usr/local/bin/ray /usr/local/lib/ray /Users/fred/bin \
/sw/bin )

If you are running the bash shell then you would look for an entry
in the .profile file something like:

export PATH=/usr/local/bin:/Users/fred/bin:/sw/bin:$PATH

In both these cases if user fred has a folder bin in their home folder
you can use the link_to or link_to_bash scripts (found in the source distribution
src/bin folder) to create alias to the ESP-r executables that you want to use:
  cd
  cd bin
  ./link_to_bash /opt/esru/esp-r/bin

Once you have updated either the .cshrc file or the .profile file then you
will need to log out and then back in again.  To see if the environment
variables are correct give the following command:

  which prj
  which bps

If the answer back is 'Users/fred/bin/prj' or '/opt/esru/esp-r/bin/prj' then the environment variables were set.

If you are working with existing models you should change the
folder focus in the X11 terminal to the model configuration folder
and start the project manager with the pattern:

  prj -model my_model.cfg

Once ESP-r is working you can remove the_file_name.tar.gz


Where to get more information

The ESP-r download pages have separate folders for each operating 
system. Further information is available on issues related to setup 
of an OSX machine to work with ESP-r.


