Steps to create or use the ESP-r installers on OSX
                             June 2010

There are two patterns used to create an installer for ESP-r for use
on OSX machines.  One is via a single-file self extractor based on
the 'makeself' script typically used in Linux and the second is to 
use compressed archive files. Both of these will be covered in this 
document.

If you want to USE the self-extractor or compressed archive file
please skip down to the relevant section.  On some OSX computers
the single-file self extractor does not work correctly.



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 with a command such as:

  ./Install -d /opt/esru --gcc3 --compiler_version -3.4 --reuse_ish_calcs
  or
  ./Install -d /opt/esru --gcc4 --compiler_version -4.3 --reuse_ish_calcs

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

  ./Install --help

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`

A similar process is taken for 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.

Either remove the /opt/esru/esp-r folder or at least
remove the executables from the /opt/esru/esp-r/bin folder.

Clear the source (via a make clean) and compile a new GTK 
version of esp-r.

  ./Install -d /opt/esru --gcc3 --compiler_version -3.4 --reuse_ish_calcs
  or
  ./Install -d /opt/esru --gcc4 --compiler_version -4.3 --reuse_ish_calcs
 
Again remove the subversion files from the /opt/esru folders.




Building a self-extractor

The self-extractor for ESP-r on a Mac is based on a package called 
makeself (which also works on Linux and in the Cygwin environment
of Windows PCs). Makeself is a script which can be installed as part
of the Darwin Ports and is also  downloaded from
<http://megastep.org/makeself>. It allows a pre-compiled version 
of ESP-r to be extracted on a users computer with minimal interaction.
Unfortunately it does not seem to extract properly on most OSX 10.5 and
10.6 computers.

Create a folder /opt/precompiled_for_osx

  sudo mkdir /opt/precompiled_for_osx

Then create a tar file of the /opt/esru/esp-r folders (the example below 
includes a version in the name of the tar file which you may
wish to change to reflect the current version number). If you compiled
an X11 version of ESP-r use the following:

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

and move it into /opt/precompiled_for_osx.

Compile and create the tar file of the GTK distribution and gzip it and
place it in the precompiled_for_osx folder (as above). 

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

Remember to remove any older *.tar.gz files from the precompiled_for_osx
folder so that are not included in the installer run file.

Next, Edit the setup script (setup) to include the specific names 
of the gzipped tar files.

In folder /opt/precompiled_for_osx along with the gziped tar files
there are several other files as follows:

License (text which is used to advise the user on license conditions).
setup_osx (a script which tells makeself.sh what to do during the 
extraction process.

The file that does most of the work is setup_osx.  This needs to be edited
slightly to include the specific ...tar.gz files.  The other
files are helper applications that setup_osx is going to copy.

The way that the self extractor is created is via a command similar
to the one below (adapt for your makeself location and version):

sudo /opt/local/bin/makeself pre_compiled_for_osx esp-r_v11.9_osx_precomp_intel.run "ESP-r V11.9 distribution Intel for OSX (/opt/esru)" ./setup

The tokens in the above command are as follows:

makeself.sh or makeself is a general script that creates installers. makeself-2.1.5 
can be downloaded from the web and it will create its own executables.  
The command includes the full path to where makeself.sh is located on your 
machine. 

The 2nd token is the name of the folder where the files to be installed are 
located (as noted in the first step). 

The 3rd token is the name of the 'run' file that is going to be created (a run 
file is the finished esp-r installer that will be placed on the web). 

The 4th token is a quoted string which is the message that will be printed 
out when the installer runs. 

The 5th token ./setup_osx or ./setup are the edited setup scripts within the 
pre_compiled_for_osx folder. This script needs to have a chmod a+x done on it.

It is A REALLY GOOD IDEA to test use of the self-extractor on a clean machine.



Creating the compressed tar files for alternative install procedure

For machines where the self-extractor does not work it is possible to
take the newly compiled distribution of ESP-r in /opt/esru/esp-r and
put it in a tar file and compress it.

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. Just to be certain, try running several of the new
ESP-r executables.  To ensure the correct path is included in the tar 
file create the tar file via the following commands:

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

Now clean up the source distribution via a 'make clean' command. As the
example models and databases will be ok all you need to do is to remove
the executable files form /opt/esru/esp-r/bin and then recompile (but
say no to the databases and example models).

After compiling the GTK version create a compressed tar file for
this via the commands

  cd /
  sudo tar cf esp-r_gtk_v11.9_osx_intel_in_opt.tar opt/esru
  sudo gzip -9 esp-r_gtk_v11.9_osx_intel_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
./clm:
        /usr/X11/lib/libX11.6.dylib (compatibility version 9.0.0, current version 9.0.0)
        /usr/local/lib/libstdc++.6.dylib (compatibility version 7.0.0, current version 7.10.0)
        /usr/lib/libxslt.1.dylib (compatibility version 3.0.0, current version 3.12.0)
        /usr/lib/libxml2.2.dylib (compatibility version 9.0.0, current version 9.16.0)
        /usr/local/lib/libgfortran.3.dylib (compatibility version 4.0.0, current version 4.0.0)
        /usr/local/lib/libgcc_s.1.dylib (compatibility version 1.0.0, current version 1.0.0)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 111.1.5)

These libraries will typically be installed with the X11 environment 
on Apple computers. X11 is an optional installer and is required to run ESP-r

if you are using the GTK version of ESP-r then there are rather a lot of
libraries that are required. Many of these tend to be located in a /sw folder
structure which is maintained by the 'fink' development packages. 
Instructions for using 'fink' are found in a different document.

% 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)

The Intel version of ESP-r will not run on PPC computers. 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 self-extractor

If you have just created an installer you should test this on a 
separate machine to confirm that it works.  If you have downloaded 
the self-extractor `run` file it can be used via either the OSX 
terminal (which supports text interactions) or within an OSX X11 
graphics terminal.

Typically the `run` file you downloaded should be placed in /opt 
and run via a sudo command from that folder via a command (adapt 
to reflect the actual name of the `run` file).
 
  sudo ./esp-r_v11.9_osx_precomp.run

On most OSX machines a file ending in .run will be treated as 
an executable. If the installer does not execute you may have 
to issue the following command to change its permissions:

  sudo chmod a+x ./esp-r_v11.9_osx_precomp.run

There are two versions of ESP-r which can be installed. 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
so this is generally viewed as BETA software.  The GTK version also
has a number of library dependencies which are not required of
the X11 version. If you are using the self-extractor (as opposed
to compiling ESP-r) you are limited to installing either the
X11 or GTK version as they are installed to the same folder.

The installer will ask you a number of yes/no questions and, if
successful it will place an ESP-r distribution in the folders:

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

and it will create a link from /usr/esru to /opt/esru

During the install process LOOK FOR DIRECTIONS for
adapting your PATH environment variable (if required).
Once you have checked that ESP-r modules run you can
remove the installer.


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 fink
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 \
/opt/esru/esp-r/bin /opt/esru/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:/opt/esru/bin:/opt/esru/esp-r/bin:/Users/fred/bin:/sw/bin:$PATH

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

If the answer back is '/opt/esru/esp-r/bin/prj' then the environment variable
is set.  Most users will want to run ESP-r in graphics mode so you need to
give the command to start esp-r from within and X11 command window rather
than the OSX terminal (which only handles text based applications).


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.



Installing via compressed archive files

The following is a list of steps that users should take in order to install 
via a compressed archive file.

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. 
This is an optional set of packages which will be located on your 
operating system install DVD. If you see the X11 logo icon in your 
doc you probably have X11 installed. If you do not see it check in the 
Applications folder.  If it is not there then you need to install X11 from 
the DVD before proceeding.

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.

There are two version of ESP-r for OSX. One is based on 
the X11 graphics library and is a complete version of ESP-r 
but is an older style of interaction. The other version of 
ESP-r uses the GTK graphics library with a modern style of 
interaction (but it is not quite a complete port of ESP-r). 
The web page gives more information on the specific differences.

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


Section two

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 (the_file_name represents 
the name of the 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 gzip -d the_file_name.tar.gz
 
 sudo tar xf the_file_name.tar

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

You will need to set an environment variable PATH as explained above.
You will probably also need to log out and then back in again to
have the new environment variables established.

To check and see if ESP-r can be found try typing in the 
following command(s) in an X11 terminal (the OSX terminal
is only suitable for text based applications).

  which prj
  which bps

If there is a response then you should be able to start up the
ESP-r project manager via the command 'prj'.  If the application
does start up then the environment variables have been set
correctly.  

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