
 
 Installing Cygwin for ESP-r use on a Windows computer.
 
                 November 2013 version
 
 1.0 Introduction:
 
 Using ESP-r on a PC requires a compatible operating environment.
 There is, for example a Native Windows version of ESP-r, however
 some production tasks and development tasks are more robust under
 the Cygwin emulation environment on Windows computers. Cygwin 
 provides the necessary display, command shell, and low-level 
 library functions and system calls which ESP-r expects to find
 on a Linux computer, but integrated within the Windows environment.
 
 Cygwin differs from virtualization in that it exists within the
 folder structure of Windows rather than in a virtual computer
 so it naturally sees the Windows file folders and Windows Explorer
 can access the files within the Cygwin environment.  Cygwin allows
 ESP-r to run at almost the same speed as a native version.
 
 The document also discusses how to install ESP-r once Cygwin
 has been setup. There are two options: install from a 
 precompiled distribution (contact jon@esru.strath.ac.uk for
 a link to a current installer), or install from source. 
 
 Setting up cygwin requires several steps and the use of commands 
 which will be familiar to those who have used Unix/Linux. If you
 want to jump into that jungle solo then you will  not  want to 
 read the sections that follow. You would probably also want to 
 skip the information on the Cygwin web site at <http://www.cygwin.com>. 
 Cygwin can be used with Windows XP and W7. The 32bit version is more
 common but ESP-r can be built and run with the 64bit version of
 Cygwin.
 
 1.1 Before you download and install cygwin:
 
 Prior to downloading and installing cygwin ensure there is an
 administrative and normal user on your PC or that your user
 account has administrative access. In a shared environment there
 may be IT staff who maintain your computer and so it might be best
 to get them to install Cygwin on the computer.
 
 Hints: ESP-r works better if user names do not have spaces or 
 unprintable characters.  If the computer is part of a domain then 
 there are additional commands needed to create entries in the 
 /etc/passwd file and the /etc/group file.
 
 If you are going to take the entire cygwin environment you will
 need ~4GB of disk space plus space for the downloaded installation
 files. If you restrict Cyginw to packages needed to develop ESP-r 
 then you will need ~2.5GB of disk space. If you take a minimum 
 Cygwin that is sufficient to run ESP-r then you will need ~1.5GB 
 of free space for cygwin. You will need ~500 MB for ESP-r source 
 and 200 MB for the installed ESP-r X11 distribution and a bit more
 if you have both GTK and X11 versions of ESP-r.
 
 The install process tends to present fewer hassles if you do the
 Cygwin install as administrator.
 
 1.2 Installing cygwin from the web:
 
 Point a web browser at <http://www.cygwin.com> and look for the 32bit
 or 64bit installer exe files. (c:\TEMP is a good place to put it). This 
 same tool can also be used to update cygwin. These instructions are 
 based on the 2.738 version of the setup.exe.
 
 Once downloaded run the setup-x86.exe or setup-x86-64.exe and it will 
 ask the following questions:
   a) Where to get cygwin? Choose the option "internet" if this if
      you have a fast connection and will be installing cygwin on
      one machine. Choose the "download" option if you want to install
      cygwin on more than one machine. Choose the "Install from local
      directory" if you have already downloaded a cygwin distribution
      or are doing it from a CD or USB drive.
 
   b) Where to put it? Take the suggestion c:\cygwin or c:\cygwin64 and
      also the default option "all users" and "Unix file type".
      When asked about a "local package directory accept
      "c:\TEMP" if internet or download, or point to a folder
      with previously downloaded files if that is the approach
      you are taking.
  
   c) For an internet or download install you may have to set an
      appropriate proxy.
 
   d) Select a download site. 
 
 Once the ftp site has been reached the next task is to select the
 packages to install. There are essentially three levels depending 
 on how much disk space you want to allocate to cygwin and ESP-r. 
 
 If disk space is not a problem follow the instructions in section 
 1.3a (essentially you take all of particular software topics).
 If you want cygwin to support compilation of ESP-r then skip section 
 1.3b.
 
 Consider what type of window manager you would like to use. It is
 possible to replicate the GNOME or KDE window managers found on 
 Linux computers if you have lots of disk space and a fast computer. 
 There is also a minimal approach that allows for ESP-r to run
 in graphic mode without a window manager e.g. it just pops-up on
 the normal screen as an application.
 
 1.3a If disk space is not a problem -  
 
 Select all by toggling the "All -> default" to "All -> Install" for
 the main topics (you might leave at default Audio, Games, Python,
 Science, Security if these are not of interest). This could take a 
 few moments for this change to take affect.  It can take 30 minutes 
 to download All and another hour to install.
 
 1.3b Packages for ESP-r development - 
 
 If you want to be selective and only download what is required
 to compile and run ESP-r (and save download time and disk space)
 the following is a useful guide. For topics where not all packages
 are needed it may be easier to begin with "default" and manually
 add packages than to start with "Install" and remove packages.
 
  Accessibulity optional
  Admin:        Install
  Archive:      default plus p7zip zip unzip
  Audio:        default
  Base:         Install
  Audio:        default
  Database:     default
  Devel:        default plus the gcc4 versions of gcc g++ and gfortran
		        binutils, DDD, expat, file, gdb, gdk-pixbus2,
                gtk2-x11, gendef, gettext, gettext-devel, imake, make, libXaw3d,
                libgcc1, libgfortran3, libiconv, libicu, libjepg libncurses,
                libpng14, libstdc++6, libtool, libxml2, makedepend,
                openssl-dev, pkg-config, readline, subversion, subversion-tools

  Doc:          default plus man pages, xpdf
  Editors:      default plus nano, nedit, vim
  Games:        optional
  Gnome:        default plus the runtime and development versions of
		        atk, gdk-pixbuf, glib2, gtk2-engines, gtk2-engines-pixmap,
		        libgdk (related), libglib2 (related), libgtk2 (related),
		        librsvg2 (related), libxslt, libxml2, pango
		 
  Graphics:     default plus ImageMagic, ghostscript, jpeg, libpng,
                opengl, tiff
  Intepretors:  tick expect, gawk, m4, perl 
  KDE:          optional
  Libs:         default
  Mail:         optional
  Math:         optional
  MinGW:        default
  Net:          default plus ssh, openssh-server, ping, inetutils, rsync.
  Perl:         default
  Publishing:   default plus psutils
  Python:       optional
  Science:      optional
  Security:     optional
  Shells:       default plus tcsh, zsh, xterm
  System:       Install
  Text:         default plus enscript, groff, gv,less, more, textinfo
                or tick all (i.e. toggle Install) 
  Utils:        default plus bzip2, clear, cygutils, file, gnupg, keychain,
                ncurses, patch, time, units, util-linux
  Web:          default plus wget, wdiff, cadaver, neon
  X11:          default plus cygutils-x11, fonts, libXll-dev xorg-server,
                xorg-server-devel, xorg-server-extra xterm xinit, inetutils

For specifics look at the files cygwin32bit_instld_packages.txtr or
cygwin64bit_packages_installed.txt 
		
 
 1.4 Post-install patches:
                 
 After completing the list the installer will download the various
 packages. A dependency check is made and if additional libraries 
 or packages are required is it probably best to agree to install 
 them. The installer takes some time sorting out the post-install 
 so do not give up (it may look like no progress is being made)! 
 
 The first time you startup Cygwin a text based command terminal
 will start up. You should notice that standard .bashrc, .bash_profile,
 and .inputrc and .profile files will be copied into your home
 folder (within the Cygwin environment this would be /home/fred
 for a user named fred).  In particular the initial .bash_profile
 includes in the PATH the folder /home/fred/bin if it exists and
 the # are removed from the .bash_profile where the PATH is set.
 
 So on of your first tasks is to create a local bin folder:
   cd
   mkdir bin
 
 Working with graphic tools and windows within Cygwin. On the same
 web page as the setup.exe look for Cygwin/X and the users guide
 for Cygwin/X. There are lots of choices from the minimal approach
 which is based on an application called startxwin that is invoked
 from the Cygwin command shell. Startxwin retains the initial Cygwin
 command window for text applications and starts a single graphic
 X11 terminal for graphic applications such as ESP-r. If you need
 more graphic application running you can also invoke additional
 X11 terminals via issuing an "xterm &" command within the X11
 terminal. This takes the least space and computational
 resources.
 
 An alternative approach is to use XWin -multiwindow which will
 start an X server (look for the icon on the bottom task bar
 and a right-click can be used to start an X11 terminal. There is
 also an experimental XWin -mwextwm
 
 Once Cygwin is installed you can move on to the 2nd stage of 
 installing ESP-r.
 
 After login into the PC as Administrator (suggested), click on the Cygwin 
 icon on your desktop to start up a cygwin window. This emulates a Linux
 machine within your PC. Use Linux commands to go to
 the /tmp folder or create such a folder if it does not
 exist.

 
 Pick either section 1.5a, 1.5b, 1.5c depending on where you
 got the ESP-r distribution.
 
 1.5 Installing ESP-r via a windows installer
 
 If you have a native windows installer for a Cygwin version of
 ESP-r and you already have setup Cygwin you can just run the
 installer and it will populate the standard folders within the
 Cygwin directory structure (/opt/esru) with ESP-r. You can then
 start Cygwin to complete the post-install tasks.

 Go to section 1.7.
   
 1.6 Compile instructions:
 
 Once Cygwin is installed you need to alter several files so that
 cygwin starts with an appropriate PATH environment variable. This
 process is similar to that for installing from a precompiled version
 but without using the self-extracting installer.
  
 Standard cygwin will install a gfortran compiler in /usr/bin/
 If you issue the command which gfortran you should get /usr/bin/gfortran.exe
 and /usr/bin/gfortran-4.exe.  You will also need matching gcc
 and g++ compilers.  If these may be listed as g++-4.exe and gcc-4.exe.
 If this is the case then your subsequent use of the ESP-r Install
 script will need to include the directive --compiler_version -4
 in order to ensure that all of the compilers are found.
 
 Issue the command "logout" or "exit" in the Cygwin command
 window and then click on the cygwin icon on the desktop
 to re-establish the PATH environment variable and get an initial
 cygwin command shell window. 
 
 Create a source folder for the esp-r distribution. A typical
 location would be <home_folder>/Src/cvsdude. ESP-r source code is
 now available via a subversion server (source code control). The
 following set of commands is a typical sequence:
   cd
   mkdir Src
   cd Src
   mkdir cvsdude
   cd cvsdude
   svn checkhout https://espr.svn.cvsdude.com/esp-r/branches/development_branch

 Instructions for its use can be found on the ESP-r web page
 <http://www.esru.strath.ac.uk/Programs/ESP-r.htm> as well as
 the Developers Guide on the ESP-r download page.  If we want to
 compile and install ESP-r to its typical Cygwin location then
 the following command sequence will create the folder and then
 invoke the compile process:
   cd
   mkdir /opt/esru
   cd
   cd Src/cvsdude/development_branch/src
   ./Install -d /opt/esru --gcc4 --debug

 and if you want to find out what the install options are

   ./Install --help
 
 
 Install, when run as above will use the gcc4 compilers and will proceed
 much as it does under Linux or OS X. You will be asked which
 compiler [gcc] and whether you want the X11 or GTK version of the interface
 [first time try X11 as it has fewer dependencies]. Say yes to install of
 databases and training files and to keep debug symbols [say yes] and to 
 create folders within /opt/esru [say yes].

 If you want to be able to switch between the X11 and GTK versions of
 ESP-r then after compiling the X11 version create a folder for this
 as follows:
   cd /opt/esru/esp-r
   mkdir binX11
   cd bin
   cp * ../binX11
   
 Then clean up the object files and re-compile (requesting the GTK
 interface). Once that is done create a folder for the GTK versions:
 
   cd
   cd Src/cvsdude/development_branch/src
   make clean
   ./Install  ......
   (but this time there is no need for the databases and exemplar models
   because they already exit)
   
   cd /opt/esru/esp-r
   mkdir binGTK
   cd bin
   cp * ../binGTK
   
 Next locate the link_to and link_to_bash scripts and place in your home bin folder
 and run it to point at the binX11 or binGTK folder:
 
 cd
 cd bin
 ./link_to /opt/esru/esp-r/binX11
 
 If you have modified the .bash_profile file so that the local bin folder
 is first in your path then the X11 version of the executable will be
 the version used.  To switch to the GTK version re-run the link_to
 script with the bin_GTK.
 
 
 1.7 After ESP-r install:
 
 Typically users will start up an X display desktop and work within
 that. There are two general types of X display desktop. The first
 approach creates begins with the initial cygwin text console in which
 the command  startxwin is used to start up a graphic (X11) terminal 
 from which graphic applications such as ESP-r can be run.  

 If you installed as one user and then later try to use ESP-r as a 
 different user you may find that the graphic terminal does not start 
 correctly because of some hidden lock files in /tmp/.X11 or because 
 the X11 log file in /var/log cannot be written. If this happens try 
 removing these files (as Administrator).

 It may also be possible to run Cygwin in a virtual screen. See the
 Cygwin documentation for setting this up. It typically requires that
 you have installed some form of window manager (the most basic is twm).

 
 1.8 Radiance install:
 
 The precompiled ESP-r distributions no longer include a precompiled
 Radiance version 3.5 as part of the normal install process.
 
 It is possible to compile Radiance in the cygwin 
 environment. Note that the tiff related modules tend not to 
 compile, but none of these is essential for use with ESP-r. 
 Out-of-the-box (e.g. a fresh download of the standard
 Radiance distribution may lack the gendaylit application.
 
 
