 
Setting up a development environment for ESP-r on Windows

    Edited by Jon Hand, ESRU
           27 April 2012
 
These notes are intended for ESP-r developers who wish to 
work with a 'native version' of ESP-r on computers running 
WinXP or W7. There is also an alternative approach to
running ESP-r on Windows computers via Cygwin.  
 
The Windows port of ESP-r uses the standard source distribution
as well as the same GNU compiler suite as all other versions
of ESP-r. To enable this compliation process and provide access
to underlying operating system services which are normally
not provided on Windown we typically use the two packages
MinGW (Minimalist GNU for Windows) which is a Windows port 
of the GNU C, c++ and Fortran 90 compilers and MSYS 
(Minimal SYStem) which provides basic shell, make, and 
install utilities needed to support MinGW. 
 
MSYS and MinGW are hosted on SourceForge and documentation 
and links are available at <http://www.mingw.org>. A combined
installer mingw-get-inst for MinGW and MSys can be found at:
<https://sourceforge.net/projects/mingw/files/Installer/> there
is a mingw-get-inst-xxx.README.txt and a mingw-get-inst-xxx.exe
(where xxx is a date code).
 
There are a number of packages you need from this installer 
to setup MSYS and MinGW on your computer. A good place to 
put the downloaded files is C:\TEMP. The installer has tick
boxes for C C++ Fortran as well as the Msys base system and
developers tool kit. You are offered a choice to use the
in-built packages or to download a fresh list of packages
(choose the latter). You will be asked where to put it all,
use the default C:\MinGW.

Note on the sourceforge.net site are folders for contributions
which might be useful. One of the tools that comes with the
initial download is a command line tool named mingw-get. This
is a package manager with a simple syntax:
  mingw-get list  (lists available packages)
  mingw-get install packagename

For example, if part of the compiler suite was problematic
and you wanted to download again the gcc compiler you would
use a command:
  mingw-get install gcc

At the end of the install process you will find the following
structure:
C:\MinGW
    - bin  (compilers)
    - doc
    - include
    - lib
    - libexe
    - mingw32
    - msys (shells)
       - 1.0
         msys.bat (click this to start msys or make a shortcut)
         - bin (lots of executables)
         - etc
         - home (user accounts and files live here)
           - username
         - include
         - lib
         - sbin
         - share
         - var
    - share
    - var

The installer may place an Msys icon on your computer, if not
find it C:\MinGW\msys\1.0\msys.bat.  This starts a command
window with an interpreter similar to bash and sh on a Linux 
computer. It may look a bit like a DOS window, but it has
a much more powerful syntax. The command window deals with 
text based commands and can run text based applications
and scripts. For example the pattern matching tools grep and
awk are available.  A subset of the standard commands you
would find on a Linux computer are included (look in the
C:\MinGw\msys\1.0\bin).

When you start up the command window you are actually working
in C:\MinGW\msys\1.0\home\your_user_name. This is your HOME
folder when you are working within Msys. Those who are familar
with Linux would populate their HOME with folders such as
bin, Models, Src via commands (within the command window)
such as:
  cd
  mkdir bin   (for your own scripts)
  mkdir Src
  mkdir Src/cvsdude  (for ESP-r source distributions)
  mkdir Models

Remember that in the MSYS command terminal you should use Linux 
command syntax.  Applications you start from within the MSYS 
command syntax are generally restricted to the executables 
within the C:MinGW\msys\1.0\bin folder. 

Extensions to Msys

The initial command window is for text commands and applications
a better looking terminal which can be re-sized and is also 
capable of starting a graphic version of ESP-r (for debug purposes) 
is on the sourceforge.net site MSYS/Extension/rxvt. Look for a
file ending with -bin.tar.lzma. Files in the .lzma format can be
unpacked using the free 7-Zip tool for Windows <www.7-zip.org>.
Inside the .lzma file are msys-W11.dll and rxvt.exe which need to
be placed in the C:\MinGW\msys\1.0\bin folder.

Additional windows ports of applications and libraries 
can be found at <http://gnuwin32.sourceforge.net> 
From this site you want to grab the following: 
LibArt (runtime and developer) 
 
The Native Windows version of ESP-r can be compiled in two 
forms - a pure text version (useful for batch processing) 
and a graphical version based on the GTK+ libraries.  
The site <http://www.gtk.org> provides an overview of the 
GTK+ Project.  One the download tab you can find links for 
Linux, Windows 32/64 bit and OSX.  What we want is the 
Windows 32 bit version.  Look for the "bundle" link.  This 
zip file can be extracted via 7-zip (mentioned above).  The 
suggested location is C:\GTK (which should be created prior 
to running 7-zip).  Move the bundle file into C:\GTK and 
then you can right-click on it to use 7-zip.

There is a gtk+bundle.README.txt  in C:\GTK which is worth 
looking at.  It suggests updating your Windows environment 
PATH (see the discussion below).

If you download a file that ends in lzma then the Msys command you want to use is:
  tar --lzma -xvf file.tar.lzma

this will tell you what it has unpacked from the lama file. 
Additional windows ports of applications and libraries can be 
found at <http://gnuwin32.sourceforge.net>. Other sites 
are <http://www.gimp.org/~tml/gimp/win32> and 
<http://www.gimp.org/~tml/gimp/win32/downloads>.  The bundle 
method (above) is a brute force approach that provides much 
more than the run-time environment. An alternative method 
based on installing the GIMP package for windows (that is 
not discussed here).

Pkg-config is used by the compiler to denote where 
the GTK libraries and include files are located on 
your machine. You will need to add an environment 
variable to your Windows setup: 
PKG_CONFIG_PATH   C:/GTK/lib/pkgconfig 

Using mingw-get

The in-built package manager that comes with MinGW can
be used to access libraries required by ESP-r. In the
Msys command window give the following commands:

  mingw-get install msys-gmp
  mingw-get install msys-libgmp
  mingw-get install mingw32-gmp
  mingw-get install 
  mingw-get install msys-libxml2

Although you can get libxml2 via mingw-get the libxslt used
by ESP-r is not generally available so say no to the XML
option unless you are willing to compile libxslt.

Setting environment variables
 
You will need to prepend to the Path environment 
variable ;C:\Esru\esp-r\bin;C:\GTK\bin;C:\MinGW\bin 
 
These paths assume that you are going to compile ESP-r
and install the executables and databasea and example
models into C:\Esru. This avoids spaces in the paths
to the files.  Note: ESP-r sometimes has problems if 
you attempt to install it to a D drive.  


ESP-r needs a place to put new models as well as the 
results files generated by the simulator.  If you do not 
specify otherwise the default is C:\Documents and Settings\username.  
Some people prefer to define a new environment variable HOMEPATH = C:\Esru

Subversion on Windows

Access to the ESP-r source distribution is via a version
control system called subversion. You need a client and
one of the easiest to use is TortoiseSVN 
<http://tortoisesvn.net/downloads.html>. When you
install this make sure to click on the option for the
command line tool (the ESP-r installer will be looking
for an executable named svn.exe) and if it finds this
then the ESP-r modules will include information on the
specific version and branch that was used to create it.

TortoiseSVN in graphical form is accessed by right-clicking
on the Windows Explorer window and it offers most of the
facilities needed to work with ESP-r 'branches'. If you
are used to the command line then you can also issue
svn commands directly in the Msys command window.

Text editors on Windows

ESP-r source code and many ESP-r model files are ASCII
files and, by convention they maintain Unix line endings.
To work with these files you need a text editor rather 
than a word processor. The Windows notepad and Word should be
avoided.  WordPad is ok in an emergency but a much better
tool is the free NotePad++ <http://notepad-plus-plus.org>.

Locals

ESP-r uses a lot (~1 million lines) of Fortran. Fortran does
not really do international character sets and it expects
that real numbers use a period as a decimal place and that
commas are used to separate items in a line. If your locale
(France, Germany, Japan etc.) uses a comma as a decimal point then
ESP-r models quicly become corrupted.  Choose something like
a USA or UK or C locale.

Getting an ESP-r distribution

Either via the graphic subversion client or in the Msys command
window issue the following commands:

  cd
  cd Src/cvsdude
  svn checkout https://espr.svn.cvsdude.com/esp-r/branches/a_branch_name

This will create a folder with the same name as a_branch_name. If
you do not have your own 'branch' use development_branch. To find out
more read the ESP-r Developers guide (on the ESRU ESP-r downloads
page).

Compiling commands

It is possible to compile ESP-r as a graphical application based
on the GTK graphics library. Assuming that the C:\GTK folders
have been setup you can use the normal Install script:

 cd src/bin
 ./Install -d C:/Esru --gcc4 --reuse_ish_calcs


If you want to use ESP-r for production work driven by scripts or
driven by a 3rd party graphical application then you will need to
compile a pure-text based application (for some reason the
-mode text option that works on all other computing platforms
does not work on Native Windows. To compile a pure-text
version of ESP-r you may be able to do this via the standard
Install script and choose the pure-text option. If this
fails there is an alternative script called Install_dos_text_xml script
in the src/bin folder and copy it one level:

  cd src/bin
  cp Install_dos_text_xml ../

Then issue the command
  ./Install_dos_text_xml -d C:/Esru --gcc4 --reuse_ish_calcs

If you want to know more about the Installation process see
the ESP-r Developers Guide (April 2012 version). 
 
Note: the ESP-r Install script should detect that the
compilation is being done on a Native Windows computer.
If select MinGW.

When you are finished using MSYS type 'exit' in the MSYS 
command window. If you are working in an rxvt window exit 
from it first.

Using ESP-r

Assuming your Install task worked you will now have an ESP-r 
distribution on your computer.  The native windows version 
of ESP-r is a graphic application which should be invoked from 
within Windows rather than from within MSYS.  The exception 
would if you wanted to use the GNU debugger gdb and this should 
be run from within MSYS and from the folder with the source 
code and executable.

There are many ways to use these executables and example models 
and one pattern which works well for many users is listed below:

a) Create a folder for simulation models and a good place is C:\Esru\Models

b) Create an association between model configuration files (*.cfg) 
and the esp-r.bat file found in C:\Esru\esp-r\bin  One way to do 
this is to use Windows explorer and find the training folder 
e.g. C:\Esru\esp-r\training  and locate a model folder and then 
its cfg folder and right click on a file ending in .cfg  Associate 
it with the esp-r.bat file and then try clicking on the cfg file 
to see if the ESP-r project manager starts up.

c) Make a habit of opening up existing models by using Window Explorer 
to go into the cfg folder of the model and clicking on the model cfg 
file. This will ensure that all of your work is 'local' to the model.

d) copy the esp-r.bat file into the C:\Esru\Models folder and if you 
want to create a new model first go to the C:\Esru\Models folder and 
use the esp-r.bat file

Working with INNO Setup

If your goal is to create an installer for your Native Windows
ESP-r distribution there are a number of steps involved. <<this
section still to be completed>>.


Hints
 
Decide how many users you want for your computer.  If the same user 
owns the software as well as uses the software then it is easy to 
corrupt databases.  Protect yourself by having separate user accounts 
for development work and simulation project work.

A few hints for use of ESP-r on Windows machines: 
 
a) path lengths in ESP-r are limited and to ensure 
   that model file names are not truncated you should 
   place models in a location other than the users 
   desktop. C:\Esru\Models would be a good location. 
 
   Note that when you select existing models from the
   project model exemplars list you have an option to
   specify where the model will be placed. Avoid
   paths with spaces and long paths.

b) Enable an association between model .cfg files and
   the C:\Esru\esp-r\esp-r.cmd file.  Then you can
   use Windows Explorer to click on model cfg files
   and automatically start the ESP-r Project Manager.
   You can also copy the esp-r.cmd file to a folder where
   you want to create new models (e.g. c:\Esru\Models) and 
   then you can click on that cmd file to start up 
   ESP-r. 
 
c) ESP-r assumes that real numbers use a . to mark 
   decimal places and that a comma is a token 
   separator. It gets seriously confused in locales 
   where decimals are defined with commas. Please 
   switch locales before running ESP-r. 
 
d) ESP-r assumes that so-called corporate databases 
   can not be overwritten by normal users of ESP-r. 
   On Windows machines this protection is not 
   absolute and can cause potential problems. Make
   a backup of the databases and climate folders
   just to be safe.
 
e) The Windows version lacks some facilities available
   on other operating systems (e.g. click-on-bitmap, 
   select via mouse). Not every exemplar model has been 
   tested. When the unexpected happens we urge you to 
   forward comments to Jon Hand (jon@esru.strath.ac.uk) 
 
f) The Windows version will evolve so use svn commands
   to update your distribution. More information on
   subversion commands can be found in the ESP-r
   Developers Guide download site for updates. 

g) ESP-r has few 'undo' options. So for your own protection 
   make regular backups of your work.  How to make backups?  
   Use a tool such as WinZip or 7-zip and right click on the top 
   level folder of the model to create a compressed archive.  Do 
   this often.  If possible give the compressed archive a name 
   that helps you remember which version of the model is held 
   in the archive.

h) If you want to transfer a model to a different computer or 
   a computer with a different operating system then you may 
   need to use one of the scripts found in the source code 
   distribution bin folder.

i) Join the ESP-r community and send your questions 
   to esp-r@lists.strath.ac.uk!

 
