
     Steps to create or use the ESP-r self extractor on Linux
                        March 2011

There are two patterns used to create an installer for ESP-r for use
on Linux computers.  One is via a single-file self-extractor 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.

Before you Install ESP-r make sure your locale on your computer
is set to one which uses a 'dot' for the decimal place
rather than a 'comma'. ESP-r gets extremely confused and tends
to corrupt models and crash if the locale is not reset.


BUILDING A SELF-EXTRACTOR

The self-extractor for ESP-r is based on a package called 
makeself-2.1.5. Makeself is a script which can be downloaded from
<http://megastep.org/makeself>  and it allows a pre-compiled version of 
ESP-r to be extracted on a users computer with minimal interaction.

Optional Linux software is typically installed to the /opt folder.
First check that /opt exists on your computer. If is does then
issue the following command to create and own (e.g. if your login
name is fred and your group is staff):
  sudo mkdir /opt/esru
  sudo chown fred /opt/esru
  sudo chgrp staff /opt/esru


The commands to compile a standard version of esp-r (X11 version) 
in the standard location which on Linux can be /usr/esru or /opt/esru
with a command such as:

  ./Install -d /opt/esru --gcc4 --compiler_version -4.1 --reuse_ish_calcs

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

  ./Install --help

The --gcc4 directive is required. The --compiler_version option is
sometimes needed if you have more than one version of GCC on your
computer.  Try 'which gcc' and then 'gcc --version'
to establish the version prior to running the Install script.

If the executable for the compiler is actually something 
like /usr/bin/gcc-4.1  the syntax is --compiler_version -4.1. You may
need this directive to ensure that the C compiler, C++ compiler
and Fortran compiler gfortran are consistent with each other.
Look in /usr/bin for which variants of gcc g++ and gfortran
exist on your machine.

After you have built the ESP-r distribution in /opt/esru, 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 /opt/esru. To clean these up go 
to /opt/esru and issue the following command:

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


Setting up the precompiled folder

Create a folder /opt/esru/precompiled_for_linux

  mkdir /opt/esru/precompiled_for_linux

Then create a tar file of the 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). For 32
bit Linux computers use the following:

  cd /opt/esru
  tar cf esp-r_X11_11.10_linux.tar esp-r
  gzip -9 esp-r_X11_11.10_linux.tar
  mv esp-r_X11_11.10_linux.tar.gz /opt/esru/precompiled_for_linux

If you are working on a 64 bit computer then alter the names to
avoid confusion.

  cd /opt/esru
  tar cf esp-r_X11_11.10_linux_64.tar esp-r
  gzip -9 esp-r_X11_11.10_linux_64.tar
  mv esp-r_X11_11.10_linux_64.tar.gz /opt/esru/precompiled_for_linux



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 cygwin for ESP-r development for more information about this.

To compile a GTK version 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 --gcc4 --compiler_version -4.1 --reuse_ish_calcs
 
Again remove the subversion files from the /opt/esru folders.

Create the tar file of the GTK distribution and gzip it and
place it in the precompiled_for_linux folder (as above). 

  cd /opt/esru
  tar cf esp-r_GTK_11.10_linux.tar esp-r
  gzip -9 esp-r_GTK_11.10_linux.tar
  mv esp-r_GTK_11.10_linux.tar.gz /opt/esru/precompiled_for_linux

or 

  cd /opt/esru
  tar cf esp-r_GTK_11.10_linux_64.tar esp-r
  gzip -9 esp-r_GTK_11.10_linux_64.tar
  mv esp-r_GTK_11.10_linux_64.tar.gz /opt/esru/precompiled_for_linux

Remember to remove any older *.tar.gz files from the precompiled_for_linux
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. Make sure the setup file has execute
permissions  e.g.  chmod a+x setup

In folder /opt/esru/precompiled_for_linux 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).

The file that does most of the work is setup.  This needs to be edited
slightly to include the specific ...tar.gz files.  The other
files are helper applications that setup 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.sh location):

32 bit:
sudo /home/jon/bin/makeself-2.1.5/makeself.sh precompiled_for_linux esp-r_v11.10_linux_precomp.run "ESP-r V11.10 32bit distribution" ./setup

64 bit:
sudo /home/jon/bin/makeself-2.1.5/makeself.sh precompiled_for_linux esp-r_v11.10_linux_precomp_64.run "ESP-r V11.10 64bit distribution" ./setup64

The tokens in the above command are as follows:

makeself.sh 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 is the edited setup script within the precompiled_for_linux
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.

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. The instructions for setting up cygwin include the libraries
that you will need.

If you are running the X11 version of esp-r there are only a few libraries
that the executables will be looking for (libX11.a libm.a). If you are using 
the GTK version of ESP-r then there are rather a lot of libraries that are 
required. A ldd command on an executable will list the libraries that are 
found as well as those which it wants to find.


USING or 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 within an X11 graphics terminal.

Typically the `run` file you downloaded should be placed in /tmp within
and run from that folder via a command (adapt to reflect the 
actual name of the `run` file).  For example:

  ./esp-r_v11.10_linux_precomp.run

If nothing happens it may be that the download process has removed the
execute permissions from the run file.  You can re-enable these via
the command:

  chmod a+x ./esp-r_v11.10_linux_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 libary. 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

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. 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 /home/fred/bin \
/opt/esru/esp-r/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:/usr/esru/bin:/usr/esru/esp-r/bin:/home/fred/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 an X11 command window.



INSTALLING VIA COMPRESSED ARCHIVE FILES

As an alternative, some machines do not work well with self-extractor. In this
case the gzipped tar files can be used to install ESP-r. The following is a list of
steps that users should take in order to install via a tar file.

The first step is to prepare a folder to install the ESP-r distribution. The
usual location is /opt/esru.

ESP-r requires an X11 environment to be installed. This is typically available
on all Linux machines. 

There is some information you will need. Start up an 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 Linux. 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/esru folder start
up either a terminal or and X11 terminal. In the terminal
give the following command:

  ls -l /opt

in the listing given look for the following line:

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

To create a new /opt/esru folder give the following commands. Lets
assume that your login name is fred and your group is staff.  If you
do not have permission to create these files you should either become
root when you do this or prepend the 'sudo' command to the mkdir and
chmod commands.

  cd /opt
  mkdir esru
  chmod a+x esru
  chmod a+r esru
  chmod u+w esru

Now assuming that you placed the_file_name.tar.gz in a location that
you have control of e.g. /tmp you can extract the the_file_name_tar.gz 
file to /opt/esru via:

  tar xfz the_file_name.tar.gz --directory /opt/esru

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/esru
  chown -R fred esp-r
  chgrp -R staff esp-r

You will need to set an environment variable PATH as explained above.
Currently the example link_to and profile files are not included
in the tar file version (they are listed below):

Contents of profile file:
# ~/.profile: executed by the command interpreter for login shells.
# This file is not read by bash(1), if ~/.bash_profile or ~/.bash_login
# exists.
# see /usr/share/doc/bash/examples/startup-files for examples.
# the files are located in the bash-doc package.

# the default umask is set in /etc/profile; for setting the umask
# for ssh logins, install and configure the libpam-umask package.
#umask 022

# if running bash
if [ -n "$BASH_VERSION" ]; then
    # include .bashrc if it exists
    if [ -f "$HOME/.bashrc" ]; then
	. "$HOME/.bashrc"
    fi
fi

# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/bin" ] ; then
    PATH="$HOME/bin:$PATH"
fi

Contents of link_to file:
#!/bin/csh
# create a link in /Users/jon/bin to current esp-r executables
# so can test out different variants easily.
echo "use is"
echo "link_to [folder with exectables]"
foreach i ( aco bps c2e cfg clm dfs e2r ecnv eco grd ish mfs mld mrt pdb prj pro res viewer )
  if ( -f $1/$i )then
    if ( -f $HOME/bin/$i ) rm -f $HOME/bin/$i
    ln -s $1/$i $HOME/bin/$i
    echo $i " is now pointing to "$1/$i
  endif
end

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

DEPENDENCIES

The GTK version of ESP-r uses the following libraries (list generated via
a ldd ./prj command) on a Ubuntu 10.4 LTS computer:
	linux-gate.so.1 =>  (0x00147000)
	libgtk-x11-2.0.so.0 => /usr/lib/libgtk-x11-2.0.so.0 (0x002c5000)
	libgdk-x11-2.0.so.0 => /usr/lib/libgdk-x11-2.0.so.0 (0x0088f000)
	libatk-1.0.so.0 => /usr/lib/libatk-1.0.so.0 (0x00110000)
	libgio-2.0.so.0 => /usr/lib/libgio-2.0.so.0 (0x007c3000)
	libpangoft2-1.0.so.0 => /usr/lib/libpangoft2-1.0.so.0 (0x00a7a000)
	libgdk_pixbuf-2.0.so.0 => /usr/lib/libgdk_pixbuf-2.0.so.0 (0x0012c000)
	libgfortran.so.3 => /usr/lib/libgfortran.so.3 (0x00ec6000)
	libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0x00148000)
	libpangocairo-1.0.so.0 => /usr/lib/libpangocairo-1.0.so.0 (0x0072c000)
	libcairo.so.2 => /usr/lib/libcairo.so.2 (0x0016e000)
	libpango-1.0.so.0 => /usr/lib/libpango-1.0.so.0 (0x009f7000)
	libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x001e8000)
	libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x0025e000)
	libgobject-2.0.so.0 => /usr/lib/libgobject-2.0.so.0 (0x00fb4000)
	libgmodule-2.0.so.0 => /usr/lib/libgmodule-2.0.so.0 (0x0028e000)
	libgthread-2.0.so.0 => /usr/lib/libgthread-2.0.so.0 (0x00293000)
	librt.so.1 => /lib/tls/i686/cmov/librt.so.1 (0x006b9000)
	libglib-2.0.so.0 => /lib/libglib-2.0.so.0 (0x00925000)
	libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x00b13000)
	libxml2.so.2 => /usr/lib/libxml2.so.2 (0x00cf7000)
	libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00cb2000)
	libpthread.so.0 => /lib/tls/i686/cmov/libpthread.so.0 (0x00299000)
	libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0x00ff3000)
	libXext.so.6 => /usr/lib/libXext.so.6 (0x002b2000)
	libXrender.so.1 => /usr/lib/libXrender.so.1 (0x0069a000)
	libXinerama.so.1 => /usr/lib/libXinerama.so.1 (0x006a4000)
	libXi.so.6 => /usr/lib/libXi.so.6 (0x006a8000)
	libXrandr.so.2 => /usr/lib/libXrandr.so.2 (0x006c2000)
	libXcursor.so.1 => /usr/lib/libXcursor.so.1 (0x006ca000)
	libX11.so.6 => /usr/lib/libX11.so.6 (0x0114d000)
	libXcomposite.so.1 => /usr/lib/libXcomposite.so.1 (0x006d4000)
	libXdamage.so.1 => /usr/lib/libXdamage.so.1 (0x006d8000)
	libXfixes.so.3 => /usr/lib/libXfixes.so.3 (0x006dc000)
	libz.so.1 => /lib/libz.so.1 (0x006e7000)
	libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0x006e2000)
	libpcre.so.3 => /lib/libpcre.so.3 (0x00738000)
	libresolv.so.2 => /lib/tls/i686/cmov/libresolv.so.2 (0x006fc000)
	libselinux.so.1 => /lib/libselinux.so.1 (0x00710000)
	/lib/ld-linux.so.2 (0x00af6000)
	libpixman-1.so.0 => /usr/lib/libpixman-1.so.0 (0x00769000)
	libdirectfb-1.2.so.0 => /usr/lib/libdirectfb-1.2.so.0 (0x00c09000)
	libfusion-1.2.so.0 => /usr/lib/libfusion-1.2.so.0 (0x00861000)
	libdirect-1.2.so.0 => /usr/lib/libdirect-1.2.so.0 (0x0086b000)
	libpng12.so.0 => /lib/libpng12.so.0 (0x00a3a000)
	libxcb-render-util.so.0 => /usr/lib/libxcb-render-util.so.0 (0x00881000)
	libxcb-render.so.0 => /usr/lib/libxcb-render.so.0 (0x00886000)
	libxcb.so.1 => /usr/lib/libxcb.so.1 (0x00a5f000)
	libexpat.so.1 => /lib/libexpat.so.1 (0x00aa1000)
	libXau.so.6 => /usr/lib/libXau.so.6 (0x009ef000)
	libXdmcp.so.6 => /usr/lib/libXdmcp.so.6 (0x00ac8000)

The X11 version of ESP-r has the following dependencies (on a Ubuntu 10.4 LTS computer)
	linux-gate.so.1 =>  (0x00afc000)
	libX11.so.6 => /usr/lib/libX11.so.6 (0x00110000)
	libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x0022d000)
	libxslt.so.1 => /usr/lib/libxslt.so.1 (0x006cc000)
	libxml2.so.2 => /usr/lib/libxml2.so.2 (0x00323000)
	libgfortran.so.3 => /usr/lib/libgfortran.so.3 (0x00a1d000)
	libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0x0044e000)
	libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00671000)
	libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0x00474000)
	libxcb.so.1 => /usr/lib/libxcb.so.1 (0x005d4000)
	libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0x00f3c000)
	/lib/ld-linux.so.2 (0x00d2d000)
	libz.so.1 => /lib/libz.so.1 (0x00ece000)
	libXau.so.6 => /usr/lib/libXau.so.6 (0x00fed000)
	libXdmcp.so.6 => /usr/lib/libXdmcp.so.6 (0x00976000)


WHERE TO GET MORE INFORMATION

The ESP-r download pages have separate sections for each operating system. Further
information is available on issues related to setup of Linux boxes to work
with ESP-r.
