Installing Cygwin for ESP-r use on a Windows XP computer. April 2011 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 downloaded from the University of Strathclyde ESRU web site, 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 and get your fingers bitten off 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 . Cygwin can be used with Windows XP and Vista and there are reports that it works ok on Windows 7. 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. Typically the Administrator or IT staff would maintain the cygwin and ESP-r applications. If you work as a different user for normal simulation tasks then it is harder to corrupt databases and test models. Hints: ESP-r works much better if user names do not have spaces or unprintable characters. ESP-r also works better if you setup your user account to have a home folder like C:\Joe rather than the typical C:\Documents and Settings\Joe. 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 ~300 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 and click on the "install cygwin" icon. This will download a small setup.exe application (c:\TEMP is a good place to put it) which will be used to download and install cygwin components. 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.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. b) Where to put it? Take the suggestion c:\cygwin 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 (In the University of Strathclyde this is: www-cache.strath.ac.uk port 8080) 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. If you just want to run ESP-r skip to the section 1.3c. 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: tick all (i.e. toggle Install) Archive: default plus p7zip zip unzip Audio: default Base: tick all (i.e. toggle Install) Audio: default Database: default Devel: if you have space toggle to Install you will want the gcc4 versions of gcc g++ and gfortran default plus binutils, DDD, expat, file, gcc tools, gcc, gcc4-core, gcc4-fortran gcc4-g++, gcc4-java (optional), gccmakedep, 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, patch;utils, pkg-config, readline, splint, subversion, subversion-tools, swig (optional), xorg stuff. Doc: default plus the man pages and xpdf Editors: default plus nano, nedit, vim Games: optional Gnome: optional if all you want is an X11 version of ESP-r otherwise - add 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 and image libraries Intepretors: tick expect, gawk, m4, perl KDE: optional Libs: tick all except guile and tetext Mail: optional Math: optional MinGW: default Net: tick openssh, ping, inetutils, rsync. Perl: default Publishing: default plus psutils Python: optional Science: optional Security: optional Shells: default plus tcsh, zsh, xterm System: tick all (i.e. toggle 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: typically toggle to Install and then try removing most of the 100dpi fonts and the Qt items 1.3c Packages needed just to run ESP-r: If you want to be selective and only download what is required to RUN ESP-r (and save even more download time and disk space) the following is a useful guide: Admin: tick all (i.e. toggle Install) Archive: default plus p7zip zip unzip Audio: default Base: tick all (i.e. toggle Install) Database: default Devel: default plus binutils, expat, file, gcc tools, gcc, gcc4-core, gcc4-fortran, gcc4-g++, gdb, gdk-pixbus2, gtk2-x11, gendef, gettext, imake, make, libXaw3d, libgcc1, libgfortran3, libiconv, libicu, libpng14, libstdc++6, libtool, libxml2, makedepend, openssl-dev, patch-utils, pkg-config, xorg stuff. Doc: default plus xpdf Editors: default plus nano, nedit, vim Games: optional Gnome: default if all you want is an X11 version of ESP-r otherwise - add the runtime versions of atk, gdk-pixbuf, glib2, gtk2-x11-engines, libgnome2, libxslt, libxml2, pango Graphics: default plus ImageMagic Intepretors: default plus gawk and expect KDE: optional Libs: default Mail: default Math: default MinGW: default Net: default Perl: default Publishing: default Python: optional Science: optional Security: optional Shells: Install System: Install Text: default plus enscript, less, more, textinfo or tick all (i.e. toggle Install) Utils: default Web: default plus wget X11: use the minimal install list (from above). 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 by downloading a precompiled version If downloading from the ESRU web site download page at http://www.strath.ac.uk/esru. Go to the software -> ESP-r and look for downloads and the Cygwin section. Download the installer file ending in .run or .exe as well as any readme files. If it is a .run file put that in the/tmp folder of your Cygwin environment. If it is an .exe file then any location on the C: drive is ok. Read the readme file(s) and then (typically as Administrator) run the installer script (the file ends with .run within the Cygwin environment). For the .exe installer simply double click on it within Windows. The installers will guide you through the rest of the install process. No compilation is necessary because a complete executable distribution for ESP-r is included. When the script is complete, 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 /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 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 /usr/esru cd cd Src/cvsdude/development_branch/src ./Install -d /usr/esru --gcc4 --reuse_ish_calcs 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 Solaris or 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]. You will probably want to install training files [say yes] and databases [say yes], and to keep debug symbols [say yes] and to create folders within /usr/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 /usr/esru/esp-r mkdir bin_X11 cd bin cp * ../bin_X11 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 /usr/esru/esp-r mkdir bin_GTK cd bin cp * ../bin_GTK Next locate the link_to script and place it is your home bin folder and run it to point at the bin_X11 or bin_GTK folder: cd cd bin ./link_to /usr/esru/esp-r/bin_X11 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 install via the .run file or .exe 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.