Installation instructions for GRASS on MS-Windows with Cygwin (winGRASS)

  1. Program installation
  2. Installing data
  3. Setting up an icon on the Desktop
  4. Troubleshooting
  5. Manually installing packages
  6. Reporting bugs

Prerequisites:

This UNIX oriented GRASS 6.4 for Windows version requires the Free Cygwin UNIX compatibility software (alternatively, there is also a native WinGRASS package available).

Installation

Part 1: Cygwin installation:
  1. Go to http://cygwin.com and download setup.exe. Note down the path where you saved it, we'll need it later!
  2. Run setup.exe:
    1. Select "Install from Internet"
    2. Select "Root install Directory": go ahead with default settings ("Next"). However, it is recommended to install Cygwin under a directory whose name doesn't contain spaces or tabs.
    3. Select "Local Package Directory": any directory is fine with sufficient disk space. Here the downloaded packages will be cached.
    4. Select "Your Internet Connection": direct or proxy as appropriate
    5. Select a mirror site close-by. It will fetch the list of packages.
    6. Select packages: In addition to the core requirements several packages are quite useful and some GRASS modules won't work without them (Click on "Skip" to toggle the selection of a package):
    7. After selection of these extra packages continue with "Next". It will take a while to download all Cygwin packages and install them...
Part 2: GRASS GIS installation:
  1. Create a shortcut to the previously saved Cygwin "setup.exe" (see above)
  2. Since we cannot offer a signature file (setup.ini.sig), you need to add a workaround:
    Edit the shortcut Properties (in right-mouse-button menu) and add " -X" (without quotes) as parameter to "setup.exe". The -X permits to run an own setup.ini based installation.
    Example:
    Change "C:\Documents and Settings\user\Documenti\Download\setup.exe"
    to "C:\Documents and Settings\user\Documenti\Download\setup.exe" -X
  3. Rename the shortcut name to "Cygwin-Setup" (you may want to move it to the Desktop)
  4. Run this "Cygwin-Setup" program again in order to fetch Cygwin updates (if available) and install GRASS GIS:
    1. The installation dialogue will appear; accept the default settings and continue with "Next" (5 times) unless you reach the "Choose A Download Site" dialog.
    2. As "User URL", add http://grass.osgeo.org/grass64/binary/mswindows/cygwin/ and click on the "Add" button. This will prepare the installation of the GRASS GIS package.
    3. In the "Select Packages" dialog proceed with "Next" in order to download and install the GRASS GIS package and Cygwin updates as available.


To start GRASS, double-click on the Cygwin icon and run "startx" (or "startxwin.sh") at the command prompt. This will start X-Windows and open a new xterm window. At the xterm prompt type "grass64 -tcltk".

To start GRASS from an icon on the Desktop, see below.

In case of problems see the troubleshooting section below.


Installing data:

Create a new directory in your Cygwin home directory called "grassdata/" for your data.
For example, using the Spearfish sample dataset:
(assumes you have already downloaded the dataset and put the file in your Cygwin home directory [aka "~" or c:\cygwin\home\$USER\]) 
$ cd ~
$ mkdir grassdata/
$ cd grassdata/
$ tar xzf ~/spearfish_grass60data-0.3.tar.gz
Then start GRASS using /home/$USER/grassdata/ as your GIS data directory.


Starting Cygwin GRASS from an icon on the desktop:

copy c:\cygwin\cygwin.bat to c:\cygwin\cygwin_grass.bat

edit c:\cygwin\cygwin_grass.bat so it looks like this: (add "set GRASS_AUTOSTART=1" and "-c startx") 

@echo off

C:
chdir C:\cygwin\bin

set GRASS_AUTOSTART=1
bash --login -i -c startx

Next in your cygwin home dir add this to the end of ~/.bashrc : 

#################
# Start GRASS
if [ -n "$DISPLAY" ] && [ -n "$GRASS_AUTOSTART" ] ; then
   unset GRASS_AUTOSTART
   exec grass64
fi
#################

Finally make a shortcut from cygwin_grass.bat to the Desktop.

Download the GRASS icon and select it by right-clicking on the desktop shortcut and in "Preferences" click on Change Icon and Browse.

done!


Troubleshooting:

If some modules mysteriously fail there are a few things you can do to help diagnose the problem. If the GUI fails (for example with a "child process exited abnormally" error) your first check should be the region settings module. Try typing "g.region -p" at the command line and make sure you get reasonable values for north, south, east, west and resolution. If a module returns you to the command prompt with no activity at all, try typing "echo $?" immediately after to query the module's exit code. If that says "53" you are most likely missing a library (DLL). To find out which one run "cygcheck g.region" (replace g.region with the offending module's name). You can then search for the name of the package that contains the missing file at the Cygwin package search page. Re-run the Cygwin installer to load the missing package; it will have remembered your earlier selections. Feel free to file a bug report as well (see below).

If the GRASS mapset selection startup screen doesn't load at all, you can attempt to bypass it by giving the path to the mapset directly on the command line. For example: 

  grass64 grassdata/spearfish60/user1

From outside of GRASS you can run cygcheck to check for missing DLL libraries by first changing to GRASS's library directory: 

  cd /usr/local/grass-6.4.2/lib
  cygcheck ../bin/g.region



Installing packages by hand:

(only required if you didn't install via a GRASS mirror (with "setup.ini") from within the Cygwin installer)

The winGRASS package is just a .tar.bz2 file. It can be extracted into Cygwin's root directory (or use setup.ini as explained in above external notes), e.g.: 

$ cd /
$ tar xjf /path/to/grass-6.4.2-1.cygwin.tar.bz2
Everything will be /usr/local/grass-6.4.2, except for the grass64 script which is in /usr/local/bin.

Regarding external dependencies: the only dependencies which aren't provided by Cygwin are GDAL and Tcl/Tk. They can be downloaded above and they have to be extracted into Cygwin's root directory as well (or use setup.ini as explained in above external notes).

Please help us and report bugs: Bug report form