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:

GRASS 6.2 for Windows requires the Free Cygwin UNIX compatibility software. The next version of GRASS (starting with version 6.3) will work in Windows directly -- this is currently under active development. As GRASS has been a UNIX program for the last 20 years, and covers nearly a million lines of source code, this is a non-trivial task, so bear with us and help test if you can!

Due to the Cygwin dependency GRASS 6.2 can not be installed directly. Fortunately the Cygwin setup program is fairly easy to use, and both it and GRASS can be installed by following a few simple instructions.
(Don't panic!)

For installation of Cygwin, see http://geni.ath.cx/grass.html#toc5. The instructions given there can be used with slight modification.

Required packages:
These should all be selected for install automatically when you select the GRASS package (Database section). Look inside the setup.ini file to see the specific package requirements.
Optional packages:
In addition to the core requirements these packages are quite useful and some GRASS modules won't work without them: A good text editor, such as nedit, which can translate between DOS and UNIX end-of-line text formats is also handy to have around.


To start GRASS, double-click on the Cygwin icon and run "startx" at the command prompt. This will start X-Windows and open a new xterm window. At the xterm prompt type "grass62".

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 grass62
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: 

  grass62 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.2.3/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.2.3-1.cygwin.tar.bz2
Everything will be /usr/local/grass-6.2.3, except for the grass62 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

Last changed: $Date: 2008-09-02 22:10:44 +0000 (Tue, 02 Sep 2008) $