
        Steps to create or use the ESP-r self extractor on Cygwin
                            November 2013

There are two patterns used to create an installer for ESP-r for use
on Cygwin emulators within Windows computers.  One is to use the
INNOSetup environment which runs as a native Windows installer (similar
to that used for the Native Windows version of ESP-r) and lastly via
compressed archive files.
  
These will be covered in this document.  We suggest you read the
full instructions prior to attempting any of the suggested tasks.

If you just want to use the self-extractors or compressed archive file
please skip down to the relevant section.

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


Building a Cygwin version of ESP-r

The compile process for ESP-r is as follows. First, start Cygwin. Optionally 
start up a graphic terminal in Cygwin via startxwin.  The following 
commands are done within Cygwin.

  cd /
  mkdir opt    (if it does not exist)
  mkdir esru

  cd
  mkdir Src
  cd Src
  svn checkout https://espr.svn.cvsdude.com/esp-r/branches/development_branch
  cd development_branch
  cd src
  ./Install -d /opt/esru --gcc4 --debug
  (say yes to debug and databases and example models)
  (choose the X11 or GTK interface option)

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

  ./Install --help

The --gcc4 directive assumes that you are using version 4 of the GCC
complers. Next, the directive --compiler_version -4.1 is useful if 
the executable for the compiler is actually something like /usr/bin/gcc-4.1. 
You may need this directive to ensure that the C compiler, C++ compiler
and Fortran compiler are consistent with each other. Look in /usr/bin for 
variants of gcc g++ and gfortran exist on your machine.

If you want to enable both the X11 and GTK versions of ESP-r
on a machine then you should also create folders /opt/esru/esp-r/binX11
and /opt/esru/esp-r/binGTK.  After compiling the X11 version copy
the executable files from /opt/esru/esp-r/bin to /opt/esru/esp-r/binX11
and after compiling the GTK version copy the executable files from
/opt/esru/esp-r/bin to /opt/esru/esp-r/binGTK. 

Look for the link_to and link_to_bash scripts in src/bin. These should be 
placed in a bin folder in your Cygwin home folder (create this folder if 
it does not already exist). After both versions of ESP-r have been compiled 
you can run the link_to script with the full path to the version of the executables
that you want to use.

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 /usr/esru. To clean these up go 
to /usr/esru and issue the following command:

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

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

  cd /
  tar cf esp-r_12_0_cygwin.tar opt/esru
  gzip -9 esp-r_12_0_cygwin.tar


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.


Building a Native windows Installer

The Native windows installer is based on Inno Setup and uses an *.iss
file (found in the src/manual/OS/Cygwin folder). The compile process
for ESP-r is essentially the same as above.

Folder struction for Inno Setup. Following the pattern of the Native 
Windows installer you should create a folder structure:

  c:\Installer_cygwin_esp
  c:\Installer_cygwin_esp\Installer
       iss file goes here
  c:\Installer_cygwin_esp\Source
  c:\Installer_cygwin_esp\Srouce\esru

Using Windows file manager copy C:cygwin\opt\esru\esp-r into
the c:\Installer_cygwin_esp\Srouce\esru  folder

Change into the c:\Installer_cygwin_esp\Source and double click on the
iss file to start Inno Setup. Adapt the name of the output file name
and the version number to reflect the SVN revision and branch name.

Compile the installer with Inno Setup and test the resulting executable
on a different machine.


Using the Native Windows Installer

If you are using the Native Windows Installer it provides instructions
for setting up Cygwin as well as instructions for steps to take
prior to running the installer and post-install instructions for
adapting the Cygwin environment so that the desired version of
ESP-r can be found and used. The Native Windows Installer includes
both the X11 and GTK versions of ESP-r. The instructions and provided
scripts allow you to use either of these versions.


Adapting your Cygwin environment:

The ESP-r installer does not change the system 'PATH' environment 
variable. You will need to set an environment variable PATH so that 
the folder /usr/esru/esp-r/bin is known. 

Method one - In the Cygwin command window (note alternative ./link_to commands):

  cd
  mkdir bin
  cp /usr/esru/bash_profile .bash_profile
  cp /usr/esru/link_to bin
  HOME=/home/your_user_name
  export HOME
  cd bin
  ./link_to /usr/esru/esp-r/binX11

or
  ./link_to /usr/esru/esp-r/binGTK

NOTE the DOT added to the bash_profile in the above command set. Next 
logout of cygwin and then log back in and issue the following command

  echo $PATH

what is printed out should include /home/your_home_folder_name/bin

check if one of the ESP-r executables is found by giving the command:
which prj

it should report /home/your_home_folder_name/bin/prj


Method two
(In the Cygwin command window) 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 \
    /usr/esru/esp-r/binX11 )

or
  set path = ( $path /usr/local/bin /usr/local/bin/ray /usr/local/lib/ray /home/fred/bin \
    /usr/esru/esp-r/binGTK )

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/esp-r/binX11:/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 there is an answer then the environment is ok.

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 initial cygwin 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 cygwin to work
with ESP-r.


Installing via compressed archive files

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 an optional
set of packages which will be included if you follow the instructions
for setting up cygwin. If it is not there then you need to install X11 from
the cygwin setup.exe application (in Windows) 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.

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 /usr/esru folder give the following commands. Lets
assume that your login name is fred and your group is staff.

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

Next, move the tar.gz file to / and uncompress it.

  cp the_file_name.tar.gz /
  cd /
  gzip -d the_file_name.tar.gz
  chown fred the_file_name.tar
  chgrp staff the_file_name.tar
  tar xf the_file_name.tar

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.
But the pre-compiled archive files will have the ESP-r executables in
a bin folder rather than binX11 and binGTK.

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