Using Eclipse to develop GRASS Python programs: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
(+ see also)
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
         
= How to use Eclipse to develop Python scripts that access GRASS object =
= How to use Eclipse to develop Python scripts that access GRASS object =
   
   
Recent releases of GRASS have emphasised the use of Python as the language of choice for developing scripts which access GRASS objects and can be used to automate operations without GRASS running.
Recent releases of GRASS have emphasized the use of Python as the language of choice for developing scripts which access GRASS objects and can be used to automate operations without GRASS running.
   
   
This short tutorial shows how to set up a complete development environment using the Eclipse IDE to develop, debug and run Python programs that access GRASS objects. These instructions apply to MS-Windows and Linux, and probably Mac as well, since all the packages required are open source software which runs on all three platforms.
This short tutorial shows how to set up a complete development environment using the Eclipse IDE to develop, debug and run Python programs that access GRASS objects. These instructions apply to MS-Windows and Linux, and probably Mac as well, since all the packages required are open source software which runs on all three platforms.
Line 15: Line 14:
* Optionally, other plugins for Eclipse
* Optionally, other plugins for Eclipse
   
   
==== GRASS 6.4.0RC4 and Python 2.6.x ====
==== GRASS 6.4 and Python 2.6.x ====


Many Linux distributions already include GRASS in their packaging but you must ensure you download the latest (GRASS 6.4.0RC4) release for Linux, MS-Windows, and Mac, available in binary (executable) from the GRASS {{website|download|download site}}, and install it as instructed for your platform. You will also need to download Python 2.6 for your platform from the [http://www.python.org Python.org site] and install it as required for your platform making a note of where the python executable (python.exe in MS-Windows) is installed. Most recent Linux already come with Python 2.6.2 installed.  
Many Linux distributions already include GRASS in their packaging but you must ensure you download the latest GRASS 6.4.x release for Linux, MS-Windows, and Mac, available in binary (executable) from the GRASS {{website|download|download site}}, and install it as instructed for your platform. On Windows install the stand-alone WinGRASS and not the OSGeo4W GRASS version. You will also need to download Python 2.6 for your platform from the [http://www.python.org Python.org site] and install it as required for your platform making a note of where the python executable (python.exe in MS-Windows) is installed. Most recent Linux already come with Python 2.6.2 installed.


==== Eclipse ====
==== Eclipse ====
Line 28: Line 27:
The current release is 1.4.5 and to install it you should use the Eclipse Update Manager mechanism, as detailed below.
The current release is 1.4.5 and to install it you should use the Eclipse Update Manager mechanism, as detailed below.


Open the Eclipse platform and click on the Help → Software Updates menu entry, click on the Available Software tab and click on the Add Site button. This will open a dialog box where you insert the following URL:  http://pydev.sourceforge.net/updates/ . Then press OK and follow the instructions. This will result in the Pydev plug-in being automatically downloaded and installed among your other Eclipse plug-ins and furthermore it will automatically inform you in future when new updates are available. The Home page for Pydev is: http://pydev.sourceforge.net/ .
Open the Eclipse platform and click on the Help → Software Updates menu entry, click on the Available Software tab and click on the Add Site button. This will open a dialog box where you insert the following URL:  http://pydev.org/updates/ . Then press OK and follow the instructions. This will result in the Pydev plug-in being automatically downloaded. Click on the install button to install it among your other Eclipse plug-ins. Furthermore it will automatically inform you in future when new updates are available. The Home page for Pydev is: http://pydev.org/ .
At this point you have all the software pre-requisites installed, ready for the next step.
At this point you have all the software pre-requisites installed, ready for the next step.


* Note: check first if your distribution provides the "eclipse-pydev" extension (name may vary)
==== Subversive SVN Connector ====
Same as for Pydev, but using this link: http://community.polarion.com/projects/subversive/download/eclipse/archive/I20091009-1900/
* Note 1: check first if your distribution provides the "eclipse-subclipse" extension (name may vary)
* Note 2: this link can be already present, to be activated in "Manage sites" (check first there).


==== Creating a new project ====
==== Creating a new project ====


When you first open the Eclipse platform after a new installation you will be asked to set-up a workspace, which will normally be in your home directory by default, then you will see  a Welcome screen with various buttons. Click on the one that opens the Eclipse workspace, which will be empty and probably be Java oriented.
When you first open the Eclipse platform after a new installation you will be asked to set-up a workspace, which will normally be in your home directory by default, then you will see  a Welcome screen with various buttons. Click on the one that opens the Eclipse workspace, which will be empty and probably be Java oriented.
To change it to be Python oriented you must open what in Eclipse is called a "perspective", which is a combination of views and windows which suits the plug-in you are actually using at any one time. So, go to the Window → Open Perspective sub-menu and select Pydev. This will open the Pydev perspective where most of your development work will be done, and since new development starts with a new Project, now go to the File → New menu and select Pydev Project, and follow the prompts to create a new empty Python project which we will name Myproject. Finally create the following new Python source program by right-clicking the Myproject source tree and selecting New → File from the menu. Name the file test.py (including the extension) and when the empty file opens on your workspace paste the following lines:
To change it to be Python oriented you must open what in Eclipse is called a "perspective", which is a combination of views and windows which suits the plug-in you are actually using at any one time. So, go to the Window → Open Perspective sub-menu and select Pydev. This will open the Pydev perspective where most of your development work will be done, and since new development starts with a new Project, now go to the File → New menu and select Pydev Project, and follow the prompts to create a new empty Python project which we will name Myproject.
 
import os
import grass
env = grass.gisenv()
print env
#List all environment variables
for key, value in os.environ.items(): print key, value
#Print region extent
r = grass.read_command("g.region", flags='p' )
print r
 
Save the file but don't run it yet because you will only get a number of serious error messages! which brings us to the final step...


==== Configuring Eclipse and Pydev ====
==== Configuring Eclipse and Pydev ====
Line 56: Line 52:


Open the Window → Preferences menu, expand the Pydev entry and select Interpreter - Python. Sometime Eclipse can automatically detect the location of your Python interpreter, in which case it will appear in the top right box: but if it didn't simply add it via the New button (remember you made a note of its location earlier on!).
Open the Window → Preferences menu, expand the Pydev entry and select Interpreter - Python. Sometime Eclipse can automatically detect the location of your Python interpreter, in which case it will appear in the top right box: but if it didn't simply add it via the New button (remember you made a note of its location earlier on!).
In the bottom box add the following New Folders to the ones automatically added by Eclipse, and which point to the GRASS libraries (in Windows/Mac(?) they will be located within the GRASS installation directory tree):
In the bottom box add the following New Folders to the ones automatically added by Eclipse, and which point to the GRASS libraries (in MacOS they will be located within the GRASS installation directory tree and may not be accessible using Eclipse browser pointing to "/Applications/GRASS-6.4.app", however, you can create symbolic links of the folders shown below within a different library folder such as "/Library/GRASS/6.4" and then add then using Eclipse):


Linux:
  /usr/lib/grass64/etc
  /usr/lib/grass64/etc
  /usr/lib/grass64/etc/python
  /usr/lib/grass64/etc/python
/usr/lib/grass64/bin
  /usr/lib/grass64/scripts
  /usr/lib/grass64/scripts
  /usr/lib/grass64/bin
 
MacOS:
  /Applications/GRASS-6.4.app/Contents/MacOS/lib
/Applications/GRASS-6.4.app/Contents/MacOS/etc
/Applications/GRASS-6.4.app/Contents/MacOS/bin
/Applications/GRASS-6.4.app/Contents/MacOS/etc/python
 
Windows:
C:\GRASS-64\etc
C:\GRASS-64\etc\python
C:\GRASS-64\bin  


then press Apply and OK. Finally go to the Run  Configurations menu and create a new entry for test.py as follows:
then press Apply and OK. Finally go to the Run  Configurations menu and create a new entry for test.py as follows:
Line 69: Line 77:
* Click on the Environment tab and enter the following variables and values, keeping in mind that as shown they reflect my configuration.When you start GRASS it sets most of these variables but since you now want to run programs without GRASS itself running, you will have to set them yourself and find the equivalent locations for your specific configuration. If you have trouble do the following: in Windows or Linux (and Mac?) start GRASS  and in the GRASS command shell type 'export' without quotes or parameters. This will list all the variables and their values as they apply to your GRASS environment, but don't be scared by their number, just look up the few I have listed then adjust their values  accordingly:  
* Click on the Environment tab and enter the following variables and values, keeping in mind that as shown they reflect my configuration.When you start GRASS it sets most of these variables but since you now want to run programs without GRASS itself running, you will have to set them yourself and find the equivalent locations for your specific configuration. If you have trouble do the following: in Windows or Linux (and Mac?) start GRASS  and in the GRASS command shell type 'export' without quotes or parameters. This will list all the variables and their values as they apply to your GRASS environment, but don't be scared by their number, just look up the few I have listed then adjust their values  accordingly:  


Linux:
  GISBASE=/usr/lib/grass64
  GISBASE=/usr/lib/grass64
  GISRC=/home/george/.grassrc6
  GISRC=/home/george/.grassrc6
Line 75: Line 84:
  PYTHONPATH=/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/lib/grass64/lib:/usr/lib/grass64/bin:/usr/lib/grass64/scripts:/usr/lib/python2.6
  PYTHONPATH=/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/lib/grass64/lib:/usr/lib/grass64/bin:/usr/lib/grass64/scripts:/usr/lib/python2.6
  PYTHONLIB=/usr/lib/python2.6
  PYTHONLIB=/usr/lib/python2.6
MacOS:
GISBASE=/Applications/GRASS-6.4.app/Contents/MacOS
GISRC=/Users/usernamehere/.grassrc6
LD_LIBRARY_PATH=/Applications/GRASS-6.4.app/Contents/MacOS/lib
PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/Library/Frameworks/GDAL.framework/Versions/1.7/Programs/:/Applications/GRASS-6.4.app/Contents/MacOS:/Library/Frameworks/PROJ.framework/Versions/4/Programs/:/Applications/GRASS-6.4.app/Contents/MacOS/lib:/Applications/GRASS-6.4.app/Contents/MacOS/scripts:/Applications/GRASS-6.4.app/Contents/MacOS/etc:/Applications/GRASS-6.4.app/Contents/MacOS/bin:/Applications/GRASS-6.4.app/Contents/MacOS/etc/python:/usr/X11/bin
Windows:
GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-4-SVN\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-4-SVN\msys\bin\sh.exe


and Apply all of them.
and Apply all of them.
* Now click on the Interpreter tab to verify that the interpreter has been correctly located and Pyhonpath correctly set.
* Now click on the Interpreter tab to verify that the interpreter has been correctly located and Pythonpath correctly set. Press OK to exit and now you are ready to run or debug your first Python program from Eclipse!
 
==== Running a test program ====
 
Finally create the following new Python source program by right-clicking the Myproject source tree and selecting New → File from the menu. Name the file test.py (including the extension) and when the empty file opens on your workspace paste the following lines:
 
<source lang="python">
import os
import grass.script as grass
env = grass.gisenv()
print env
#List all environment variables
for key, value in os.environ.items(): print key, value
#Print region extent
r = grass.read_command("g.region", flags='p' )
print r
</source>


Press OK to exit and now you are ready to run or debug your first Python program from Eclipse! Press the Run button in the Run Configuration dialog, or from the Run menu select 'Run'.
Save the file and press the Run button in the Run Configuration dialog, or from the Run menu select 'Run'.


== See also ==
== See also ==


* [[Eclipse]] in general
* [[Eclipse]] in general
* [[Using Eclipse 4.5 (Mars) on Windows 7]]
{{Python}}


[[Category:Development]]
[[Category: FAQ]]
[[Category:FAQ]]
[[Category: Documentation]]
[[Category: Development]]

Latest revision as of 12:29, 31 August 2015

How to use Eclipse to develop Python scripts that access GRASS object

Recent releases of GRASS have emphasized the use of Python as the language of choice for developing scripts which access GRASS objects and can be used to automate operations without GRASS running.

This short tutorial shows how to set up a complete development environment using the Eclipse IDE to develop, debug and run Python programs that access GRASS objects. These instructions apply to MS-Windows and Linux, and probably Mac as well, since all the packages required are open source software which runs on all three platforms.

Please note that this is not an Eclipse, nor a Python, nor a GRASS tutorial. It is just a description on how to get all the above to work together. It assumes some (but not much, because I don't have much!) knowledge of all the above.

Prerequisites (Release versions are as at the time of writing)

  • GRASS 6.4 and Python 2.6.x
  • Eclipse 3.4.x
  • Pydev 1.4.5 Eclipse plug-in for Python
  • Optionally, other plugins for Eclipse

GRASS 6.4 and Python 2.6.x

Many Linux distributions already include GRASS in their packaging but you must ensure you download the latest GRASS 6.4.x release for Linux, MS-Windows, and Mac, available in binary (executable) from the GRASS download site, and install it as instructed for your platform. On Windows install the stand-alone WinGRASS and not the OSGeo4W GRASS version. You will also need to download Python 2.6 for your platform from the Python.org site and install it as required for your platform making a note of where the python executable (python.exe in MS-Windows) is installed. Most recent Linux already come with Python 2.6.2 installed.

Eclipse

Eclipse 3.4.2 is the minimum version recommended, but other releases could work as well. Download it from the Eclipse download page. The Ganymede 3.4.2 release for Java developers is fine (85MB). Installing Eclipse is very easy because installations consists simply of unpacking the download package in a directory of your choice. To avoid permission problems in Linux, install Eclipse in your Home directory or a subdirectory.

Pydev

Pydev is an Eclipse plugin that adapts the Eclipse platform to the specific needs of Python program development, debugging and testing. It is not the only Python plugin available, but the one largely recommended. The current release is 1.4.5 and to install it you should use the Eclipse Update Manager mechanism, as detailed below.

Open the Eclipse platform and click on the Help → Software Updates menu entry, click on the Available Software tab and click on the Add Site button. This will open a dialog box where you insert the following URL: http://pydev.org/updates/ . Then press OK and follow the instructions. This will result in the Pydev plug-in being automatically downloaded. Click on the install button to install it among your other Eclipse plug-ins. Furthermore it will automatically inform you in future when new updates are available. The Home page for Pydev is: http://pydev.org/ . At this point you have all the software pre-requisites installed, ready for the next step.


  • Note: check first if your distribution provides the "eclipse-pydev" extension (name may vary)

Subversive SVN Connector

Same as for Pydev, but using this link: http://community.polarion.com/projects/subversive/download/eclipse/archive/I20091009-1900/

  • Note 1: check first if your distribution provides the "eclipse-subclipse" extension (name may vary)
  • Note 2: this link can be already present, to be activated in "Manage sites" (check first there).

Creating a new project

When you first open the Eclipse platform after a new installation you will be asked to set-up a workspace, which will normally be in your home directory by default, then you will see a Welcome screen with various buttons. Click on the one that opens the Eclipse workspace, which will be empty and probably be Java oriented. To change it to be Python oriented you must open what in Eclipse is called a "perspective", which is a combination of views and windows which suits the plug-in you are actually using at any one time. So, go to the Window → Open Perspective sub-menu and select Pydev. This will open the Pydev perspective where most of your development work will be done, and since new development starts with a new Project, now go to the File → New menu and select Pydev Project, and follow the prompts to create a new empty Python project which we will name Myproject.

Configuring Eclipse and Pydev

Eclipse is highly configurable, but for our purpose we will only look at the configuration required for Python use. There are three preferences menus you should know, the Window (or Eclipse) Preferences menu, the Project Properties menu, and the Run or Debug Configuration menu, but for our needs we will just look at Window and Run Configuration.


Open the Window → Preferences menu, expand the Pydev entry and select Interpreter - Python. Sometime Eclipse can automatically detect the location of your Python interpreter, in which case it will appear in the top right box: but if it didn't simply add it via the New button (remember you made a note of its location earlier on!). In the bottom box add the following New Folders to the ones automatically added by Eclipse, and which point to the GRASS libraries (in MacOS they will be located within the GRASS installation directory tree and may not be accessible using Eclipse browser pointing to "/Applications/GRASS-6.4.app", however, you can create symbolic links of the folders shown below within a different library folder such as "/Library/GRASS/6.4" and then add then using Eclipse):

Linux:

/usr/lib/grass64/etc
/usr/lib/grass64/etc/python
/usr/lib/grass64/bin
/usr/lib/grass64/scripts

MacOS:

/Applications/GRASS-6.4.app/Contents/MacOS/lib
/Applications/GRASS-6.4.app/Contents/MacOS/etc
/Applications/GRASS-6.4.app/Contents/MacOS/bin
/Applications/GRASS-6.4.app/Contents/MacOS/etc/python

Windows:

C:\GRASS-64\etc
C:\GRASS-64\etc\python
C:\GRASS-64\bin 

then press Apply and OK. Finally go to the Run Configurations menu and create a new entry for test.py as follows:

  • Click on Python Run, then click on the New configuration icon, the first at the top. Provide a Name, Project and Module names either manually or by browsing and press Apply to create the new configuration.
  • Click on the Environment tab and enter the following variables and values, keeping in mind that as shown they reflect my configuration.When you start GRASS it sets most of these variables but since you now want to run programs without GRASS itself running, you will have to set them yourself and find the equivalent locations for your specific configuration. If you have trouble do the following: in Windows or Linux (and Mac?) start GRASS and in the GRASS command shell type 'export' without quotes or parameters. This will list all the variables and their values as they apply to your GRASS environment, but don't be scared by their number, just look up the few I have listed then adjust their values accordingly:

Linux:

GISBASE=/usr/lib/grass64
GISRC=/home/george/.grassrc6 		
LD_LIBRARY_PATH=/usr/lib/grass64/lib 		
PATH=/home/george/local/jdk1.6.0_13/lib:/home/george/local/jdk1.6.0_13/jre:/home/george/local/jdk1.6.0_13/jre/bin/java/home/george/local/jdk1.6.0_13/jre/bin:/usr/lib/grass64:/usr/lib/grass64/bin:/usr/lib/python2.6:/usr/lib/grass64/lib:usr/lib/grass64/scripts:/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games  
PYTHONPATH=/usr/lib/grass64/etc:/usr/lib/grass64/etc/python:/usr/lib/grass64/lib:/usr/lib/grass64/bin:/usr/lib/grass64/scripts:/usr/lib/python2.6
PYTHONLIB=/usr/lib/python2.6

MacOS:

GISBASE=/Applications/GRASS-6.4.app/Contents/MacOS
GISRC=/Users/usernamehere/.grassrc6 		
LD_LIBRARY_PATH=/Applications/GRASS-6.4.app/Contents/MacOS/lib 		
PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/Library/Frameworks/GDAL.framework/Versions/1.7/Programs/:/Applications/GRASS-6.4.app/Contents/MacOS:/Library/Frameworks/PROJ.framework/Versions/4/Programs/:/Applications/GRASS-6.4.app/Contents/MacOS/lib:/Applications/GRASS-6.4.app/Contents/MacOS/scripts:/Applications/GRASS-6.4.app/Contents/MacOS/etc:/Applications/GRASS-6.4.app/Contents/MacOS/bin:/Applications/GRASS-6.4.app/Contents/MacOS/etc/python:/usr/X11/bin

Windows:

GISBASE= C:\GRASS-64
GISRC= C:\Documents and Settings\user\.grassrc6
LD_LIBRARY_PATH= C:\GRASS-64\lib
PATH= C:\GRASS-64\etc;C:\GRASS-64\etc\python;C:\GRASS-64\lib;C:\GRASS-64\bin;C:\GRASS-64\extralib;C:\GRASS-4-SVN\msys\bin;C:\Python26;
PYTHONLIB= C:\Python26
PYTHONPATH= C:\GRASS-64\etc\python
GRASS_SH= C:\GRASS-4-SVN\msys\bin\sh.exe

and Apply all of them.

  • Now click on the Interpreter tab to verify that the interpreter has been correctly located and Pythonpath correctly set. Press OK to exit and now you are ready to run or debug your first Python program from Eclipse!

Running a test program

Finally create the following new Python source program by right-clicking the Myproject source tree and selecting New → File from the menu. Name the file test.py (including the extension) and when the empty file opens on your workspace paste the following lines:

 import os
 import grass.script as grass
 env = grass.gisenv()
 print env
 #List all environment variables
 for key, value in os.environ.items(): print key, value 
 #Print region extent
 r = grass.read_command("g.region", flags='p' )
 print r

Save the file and press the Run button in the Run Configuration dialog, or from the Run menu select 'Run'.

See also