Using Eclipse 4.5 (Mars) on Windows 7

Introduction

After completing these installation instructions, you will have an IDE for GRASS that will allow you to perform the following development tasks:

Workbench

• Switch between C/C++, Python, Debug and SVN perspectives

Browsing

• Navigate the GRASS source code trunk
• Edit source code
• Select a symbol and go to to its declaration

Building

• Build the entire GRASS system
• Build an individual GRASS module

Editing

• Syntax highlighting
• Code completion assistance

Running

• Run GRASS modules and Python scripts

Debugging

• Set breakpoints
• Single step through source code
• View variables and memory values

Versioning

• Commit source code to the SVN repository
• Update source code from the SVN repository

Install TortoiseSVN

Download and install from the TortoiseSVN website.

During installation, include the "entire command line tools" so that "svn up" can be run from a Windows Command Prompt or MSYS shell.

The following path should have been added to PATH:

C:\Program Files\TortoiseSVN\bin

From Command Prompt, enter the following command:

>where svn

To run "svn up" from a Command Prompt, enter the following commands:

>cd C:\OSGeo4W\src\grass7_trunk
>svn up

To run "svn up" from a MSYS shell, enter the following commands:

$ export PATH=$PATH:/c/"Program Files"/TortoiseSVN/bin
$ cd /c/OSGeo4W/src/grass7_trunk
$ svn up

Install OSGeo4W Runtime and Development Framework

Download and install the 32bit version from the OSGeo4W website.

It will be installed in this directory:

C:\OSGeo4W

Checkout GRASS Source Code and Make Debug Build

Checkout the GRASS development branch using the SVN command from the GRASS Download website.

Open a MSYS shell.

$ cd /c/OSGeo4W/src
$ export PATH=$PATH:/c/"Program Files"/TortoiseSVN/bin
$ which svn
$ svn checkout https://svn.osgeo.org/grass/grass/trunk grass7_trunk

Run a 'debug' build.

$ cd /c/OSGeo4W/src/grass7_trunk
$ export CFLAGS='-g -Wall'
$ ./mswindows/osgeo4w/package.sh

This will take some time to complete.

Build activity is logged to this file:

C:\OSGeo4W\src\grass7_trunk\mswindows\osgeo4w\package.log

In addition to building and installing GRASS, which can be run using the created Windows desktop icon, the Eclipse workbench will be able to use these artifacts that are created during a GRASS build:

• Top-level Makefile
• Module-level Makefiles
• Symbol tables added to runtime binaries

Makefiles allow the Eclipse workbench to re-build the entire GRASS system or to re-build individual GRASS modules after source code editing.

Symbol tables allow the Eclipse debugger (GDB) to set break-points in source code, single step through source code, and view the values of source code variables and structures.

Install Doxygen and Make Documentation

Install latest Doxygen binary distribution for Windows.
Download and install from the | Doxygen website.

Install latest Graphviz binary distribution for windows.
Download and install from the | Graphviz website.

Install latest basic TeX/LaTeX system for Windows.
Download and install from the | MikTeX website.

After the TeX/LaTeX system is installed, and during the first time "make pdfdocs" is run, expect to be prompted for additional packages that must be installed to complete the TeX/LaTex system.

Open a MSYS shell.

$ export PATH=$PATH:/c/"Program Files"/doxygen/bin
$ export PATH=$PATH:/c/graphviz-2.38/release/bin
$ export PATH=$PATH:/c/"Program Files (x86)"/"MiKTeX 2.9"/miktex/bin
$ echo $PATH
$ cd /c/OSGeo4W/src/grass7_trunk/
$ make htmldocs
$ make pdfdocs

Open the HTML formatted documentation using a web browser:

file:///C:/OSGeo4W/src/grass7_trunk/html/index.html

Install GRASS Database

In your Windows Home directory, create a directory named 'grassdata'.

Example:

C:\Users\Ruth\grassdata

Download one or more GRASS 7 datasets from the GRASS GIS sample data download website to the 'grassdata' directory and decompress.

This tutorial uses the 'complete NC location' dataset.

After the 'complete NC location' has been decompressed in the 'grassdata' directory, you should see this sub-directory:

nc_spm_08_grass7

Install Eclipse Mars

Download and install the 32bit version of Java SE Runtime Environment (JRE) from the Java Download website.

Download and install the 32bit version of Eclipse IDE for C/C++ Developers from the Eclipse Mars Download website.

This tutorial installed Eclipse in this directory:

C:\eclipse-4.5-mars-32bit

Install PyDev Plug-In

Start Eclipse.

Help -> Install New Software...
Select "Add..".
Enter "PyDev" in the "Name: field.
Enter "http://pydev.org/updates/" in the Location" field.
"OK"

Check the "PyDev" option.
"Next"
"Next"
Accept the license agreement.
"Finish"

Restart Eclipse.

Install SVN Plug-In

Start Eclipse.

Install SVN plug-in.

Help -> Install New Software...
Set "Work with:" to "Mars - http://download.eclipse.org/releases/mars".
Expand "Collaboration".
Scroll down and put a check mark in the "Subversive SVN Team Provider option.
"Next"
"Next"
Accept the license agreement.
"Finish"

Restart Eclipse.

When "Subversive Connector Discovery" prompts you for a selection, check "SVN Kit 1.8.10".
"Finish"
"Next"
"Next"
Accept the license agreement.
"Finish"
"OK" to the "security Warning".

Restart Eclipse.

Make SVN visible.

Window → Perspective → Customize Perspective...
Select the "Action Set Availability" tab.
Check the "SVN" option under "Available action sets".
"OK"

Window → Perspective → Customize Perspective...
Select the "Shortcuts" tab.
Check the "SVN" option under "Shortcut Categories".
Select the "Menu Visibility" tab.
Check the "SVN" option under "Menu Structure".
Select the "Tool Bar Visibility" tab.
Check the "SVN" option under "Tool Bar Structure".
"OK"

You should now see "SVN" on the main tool bar and the SVN tool bar available under the main toolbar.

Setup Eclipse GRASS Environment

We will start Eclipse from a Windows batch file. This will provide the opportunity to set environment variable required by both the GRASS runtime modules and the Eclipse workbench.

1. Exit Eclipse.

File -> Exit

2. Install eclipse.bat.

Using a text editor, create a Windows batch file named eclipse.bat in the top-level directory where Eclipse is installed.

The top-level Eclipse directory used in this tutorial is:

  C:\eclipse-4.5-mars-32bit

Copy the contents from eclipse.bat to the eclipse.bat file you created.

Modify the contents for your particular Windows and GRASS development environment.

Save and exit eclipse.bat.

Reference: Working with GRASS without starting it explicitly

3. Update Eclipse Icon Properties.

Update the Properties of the Eclipse startup icon that is on your Windows desktop.

Right-click on the desktop icon and change the Target field to something like this:

C:\Windows\System32\cmd.exe /D /C  C:\eclipse-4.5-mars-32bit\eclipse.bat

Select 'OK' to save the change.

Configure Eclipse Settings

Enable C/C++ Perspective

Window -> Perspective -> Open Perspective
Select 'Other...'
Select 'C/C++'
'OK'

Enable Python Perspective

Window -> Perspective -> Open Perspective
Select 'Other...'
Select 'PyDev'
'OK'

Enable Debug Perspective

Window -> Perspective -> Open Perspective
Select 'Other...'
Select 'Debug'
'OK'

Enable SVN Perspective

Window -> Perspective -> Open Perspective
Select 'Other...'
Select 'SVN Repository Exploring'
'OK'

Insert Spaces for Tabs

Window -> Preferences -> General -> Editors -> Text Editors
Set 'Displayed tab width' to 4.
Check 'Insert spaces for tabs'.
'Apply'
'OK'

Window -> Preferences -> C/C++ -> Code Style -> Formatter
Select the 'New' button to create a new profile.
Enter 'GRASS' in the 'Profile name' field.
Select 'OK'.
Select the 'Indentation' tab.
Under 'General settings', set Tab policy to 'Spaces only'.
'OK'

Uncheck Build Automatically

'Project' -> 'Build Automatically' to uncheck this option.

Change Color of Python Comments

Window -> Preferences
Expand 'PyDev'.
Select 'Editor'.
In the 'Appearance color options' window:
  Scroll down to 'Comments' and select.
  Click on the 'Color' button to bring up options.
  Select the green color that is located in the 3rd column from the left and 4th row from the top.
'OK'
'Apply'
'OK'

Create C/C++ Project

Create a C++, Makefile, Empty project

"File" -> "New" -> "Project..."
Expand "C/C++" option.
Select "C++ Project"
"Next"

Uncheck 'Use default location'.
Browse to 'C:\OSGeo4W\src\grass7_trunk'.
'OK'
Enter 'grass7_trunk' in the "Project name" field.
Expand 'Makefile project' under 'Project type'.
Select 'Empty Project' under 'Project type'.
Select 'MinGW GCC' under 'Toolchains'.
"Next"

Click on 'Advanced settings...'
Click on 'C/C++ Build'.
Click on the 'Behavior' tab.
Leave 'Build (Incremental Build)' Checked.
Enter 'default' in the text box next to 'Build (Incremental Build)' replacing any text that is already there (e.g., 'all').
'Apply'
'OK'
'Finish'

The 'grass7_trunk' project will appear in the 'Project Explorer' view.

The 'C/C++ Indexer' operation will take some time. Its progress can be monitored in the lower right-hand corner of the screen. Click on the rectangles in the corner to display progress details.

Note: This results in creating the Eclipse .project, .cproject, and .settings files in the top-level directory of the GRASS source code installation.

C:\OSGeo4G\src\grass7_trunk

Create Top-Level Make Targets

 Right-click on 'grass7_trunk' in the 'Project Explorer' view.
 Select "Make Targets"
 Select "Create..."
 Enter 'default' in the 'Target name' field.
 'OK'

Do the same for each of the following targets:

install
clean
distclean
libs
libsclean
cleandistdirs
cleanscriptstrings
manifests

Run a GRASS Python Script

Open Project.

Right-click on 'grass7_trunk' in the 'Project Explorer' view.
Click on 'Open Project'.
The Indexer and SVN cache updates will take a moment to complete.

Switch to 'PyDev' Perspective.

Click the 'PyDev' button on the 'Perspective' tool bar.

Configure Script.

Click on 'Run' on the main task bar.
Hover over 'Run As' and select 'Run configurations...' from the pop-up list.
Right-click on 'Python Run' and select 'New'.
Enter 'm.proj.py' in the 'Name' field.
Click the 'Project' 'Browse...' button.
Select 'grass7_trunk'.
'OK'
Click the 'Main Module' 'Browse...' button.
Scroll down and enter the 'scripts' -> 'm.proj' folder and select 'm.proj.py'.
'OK'
Select the 'Arguments' tab.
Enter the following string in the 'Program arguments' window:
coordinates=-111d30,45d15.551666667N proj_out="+proj=utm +zone=10 +datum=NAD27" proj_in="+proj=latlong +datum=NAD83" --v
'Apply'
'Run'

Output from the run will be displayed in the 'Console' window.

Run Script.

'Run' -> 'Run'

Output from the run will be displayed in the 'Console' window.

Change the run focus.

 'Run'
 Click on 'Run configurations...'.
 Select a configured script under 'Python Run'.
 'Run'

Output from the run will be displayed in the 'Console' window.

Note: The first time a run configuration for a Python script is performed, Eclipse discovers that it must add the Python (PyDev) 'nature' to the project. This results in creating .pydevproject and updating .project in the top-level directory of the GRASS source code installion.

C:\OSGeo4G\src\grass7_trunk

Run a GRASS C/C++ Module

Open Project.

Right-click on 'grass7_trunk' in the 'Project Explorer' view.
Click on 'Open Project'.
The Indexer and SVN cache updates will take a moment to complete.

Switch to 'C/C++' Perspective.

Click the 'C/C++' button on the 'Perspective' tool bar.

Configure Module.

Click on 'Run' on the main task bar.
Select 'Run configurations...' from the pop-up list.
Right-click on 'C/C++ Application' and select 'New'.
Enter 'r.univar' in the 'Name' field.
Click the 'Project' 'Browse...' button.
Select 'grass7_trunk'.
'OK'
Click the 'C/C++ Applications' 'Search Project...' button.
Scroll down and select 'r.univar.exe'.
'OK'
'Apply'
Select the 'Arguments' tab.
Enter the following string in the 'Program arguments' window:
map=aspect@PERMANENT
'Apply'
'Run'

Output from the run will be displayed in the 'Console' window.

Run Module.

'Run' -> 'Run'

Output from the run will be displayed in the 'Console' window.

Change the run focus.

 'Run'
 Click on 'Run configurations...'.
 Select a configured application under 'C/C++ Application'.
 'Run'

Output from the run will be displayed in the 'Console' window.

Train Eclipse

Eclipse needs to discover all the C/C++, Python and Make symbols used to build GRASS. This requires that a complete GRASS system build be performed from the Eclipse workbench. This is accomplished using the following procedure:

Start Eclipse.
Open the 'grass7_trunk' project.
Click on the project to highlight it.

Select 'Project' on the main task bar.
Hover over 'Make Targets' and select 'Build...' from the pop-up list.
Select the 'clean' option that has an empty field under the 'Location' column.
'Build'

Select 'Project' on the main task bar.
Hover over 'Make Targets' and select 'Build...' from the pop-up list.
Select the 'default' option that has an empty field under the 'Location' column.
'Build'

This will take some time to complete.

Click on the icon (stacked rectangles) in the lower right-hand corner of the workbench to view progress.

Build a GRASS C/C++ Module

A GRASS C/C++ module is built and copied to the distribution directory.

Open Project.

Right-click on 'grass7_trunk'.
Select 'Open project'.

Expand the source code tree.

Scroll down to the module.

'grass7_trunk' -> 'raster' -> r.univar

Right-click on the module folder to access its context menu.

Right-click on 'r.univar'.
Hover over 'Make Targets' and select 'Create...'.
Enter 'default' in the 'Target name' field.
'OK'

Right-click on 'r.univar'.
Hover over 'Make Targets' and select 'Create...'.
Enter 'clean' in the 'Target name' field.
'OK'

Right-click on 'r.univar'.
Hover over 'Make Targets' and select 'Build...'.
Enter 'clean' in the 'Target name' field.
'OK'

Right-click on 'r.univar'.
Hover over 'Make Targets' and select 'Build...'.
Enter 'default' in the 'Target name' field.
'OK'

Build results will be displayed in the 'Console' window.

The executable is output to the distribution directory:

'grass7_trunk' -> 'dist.i686-pc-mingw32 -> 'bin'

You can right-click on r.univar.exe' in the distribution directory and select 'Properties' to get the 'Last modified' date and time.

Build a GRASS Python Script

A GRASS Python script is not built like a GRASS C/C++ module because it is an interpreted language. The Makefile located in the directory of the script is used to install the script in the distribution directory.

Open Project.

Right-click on 'grass7_trunk'.
Select 'Open project'.

Expand the source code tree.

Scroll down to the script.

'grass7_trunk' -> 'scripts' -> m.proj

Right-click on the script folder to access its context menu.

Right-click on 'm.proj'.
Hover over 'Make Targets' and select 'Create...'.
Enter 'default' in the 'Target name' field.
'OK'

Right-click on 'm.proj'.
Hover over 'Make Targets' and select 'Build...'.
Enter 'default' in the 'Target name' field.
'OK'

The script is installed in the distribution directory:

'grass7_trunk' -> 'dist.i686-pc-mingw32' -> 'scripts'

You can right-click on 'm.proj.py' in the distribution directory and select 'Properties' to get the 'Last modified' date and time.

Debug a GRASS C/C++ Module

Switch to C/C++ perspective.

Run 'r.univar' (configured using the 'Run a GRASS C/C++ Module' instructions).

Run -> Run Configuration...
Select 'r.univar' under 'C/C++ Application.
'Run'

Open the C/C++ code to be debugged.

Double-click on:
grass7_trunk -> raster -> r.univar -> r.univar_main.c

Switch to Debug perspective.

On the top task bar:

Run -> Debug

The module will execute and stop at the 1st line in main().

Scroll down to this line:

G_get_window(&region);

After this line, set a breakpoint by double-clicking on the line number. You will see a green button appear next to the line number.

On the debug task bar:

Click on the green arrow ( Resume (F8) ).

The module will execute and stop at the breakpoint.

Hover over any variable to bring up a pop-up window to view its value.

The state of variables executed up to this point will be displayed on the 'Variables' view tab.

Debug a GRASS Python Script

Switch to PyDev perspective.

Run 'm.proj.py' (configured using the 'Run a GRASS Python Script' instructions).

Run -> Run Configuration...
Select 'm.proj.py' under 'Python Run.
'Run'

Open Python code to be debugged.

Double-click on:
grass7_trunk -> scripts -> m.proj -> m.proj.py

Switch to Debug perspective.

Scroll down to this line:

cmd = ['cs2cs'] + copyinp + outfmt + in_proj.split() + ['+to'] + out_proj.split()

After this line, set a breakpoint by double-clicking on the line number. You will see a green push-pin appear next to the line number.

On the top task bar:

Run -> Debug

The script will execute and stop at the breakpoint.

Hover over any variable to bring up a pop-up window to view its value.

The state of variables executed up to this point will be displayed on the 'Variables' view tab.

Help

| Eclipse Mars Online Help

• Workbench User Guide
• C/C++ Development User Guide

| PyDev Manual

| Subversive User Guide