Working with GRASS without starting it explicitly
GRASS sessions
It is possible to access GRASS modules without explicitly starting a "GRASS session". GRASS libraries require certain environment variables to be set. In fact a "GRASS session" is just a set of processes (e.g. a shell and/or GUI) which have the necessary environment settings, specifically:
- GISBASE needs to be set to the top-level directory of the GRASS installation.
- GISRC needs to contain the absolute path to a file containing settings for GISDBASE, LOCATION_NAME and MAPSET.
- PATH needs to include $GISBASE/bin and $GISBASE/scripts.
If the GRASS libraries are shared libraries, the loader needs to be able to find them. This normally means that LD_LIBRARY_PATH (Linux, Solaris), DYLD_LIBRARY_PATH (MacOSX) or PATH (Windows) need to contain $GISBASE/lib, although there are other means to the same end (e.g. on Linux, putting $GISBASE/lib (with $GISBASE replaced by its actual value) into /etc/ld.so.conf then running ldconfig).
Some libraries and modules use other variables. More information for most of them is available in the file $GISBASE/docs/html/variables.html. The display libraries used by d.* commands use additional variables, which are documented along with the individual drivers.
Accessing GRASS modules without starting a GRASS session
Python example
import os
import sys
gisbase = os.environ['GISBASE'] = "/usr/local/src/grass_trunk/dist.i686-pc-linux-gnu"
gisdbase = "~/grassdata"
location = "nc_spm_08"
mapset = "PERMANENT"
sys.path.append(os.path.join(os.environ['GISBASE'], "etc", "python"))
import grass.script as grass
import grass.script.setup as gsetup
gsetup.init(gisbase,
gisdbase, location, mapset)
print grass.gisenv()
Bash examples (GNU/Linux)
Below an example of a ~/.bash_profile script to set the required settings in order to access GRASS commands outside of a GRASS-session. Specifically it is for GRASS 7, and uses the version from the dist.<arch> directory in the GRASS source tree rather than an installed version.
export GISBASE=/usr/local/src/grass/svn/dist.i686-pc-linux-gnu
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat
export GRASS_WISH=wish
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=silent
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export GRASS_LD_LIBRARY_PATH="$LD_LIBRARY_PATH"
export PYTHONPATH="$GISBASE/etc/python:$PYTHONPATH"
export MANPATH=$MANPATH:$GISBASE/man
export GIS_LOCK=$$
export GRASS_VERSION="7.0.svn"
tmp=/tmp/grass6-"`whoami`"-$GIS_LOCK
export GISRC="$tmp/gisrc"
mkdir "$tmp"
cp ~/.grassrc6 "$GISRC"
The above script will allow GRASS commands to be used anywhere. Furthermore, if the ~/.Xsession sources the bash startup scripts, the settings aren't limited to interactive shells, but also work for e.g. M-! in XEmacs). Each interactive shell gets a separate "session" (i.e. a separate $GISRC file), while GUI programs share a common session.
Another example that sets some grass64 version as default under bash:
# grass environment variables
export GISBASE=/usr/local/grass-6.4.0svn
export GRASS_GNUPLOT='gnuplot -persist'
export GRASS_WIDTH=640
export GRASS_HEIGHT=480
export GRASS_HTML_BROWSER=firefox
export GRASS_PAGER=cat
export GRASS_WISH=wish
export GRASS_PYTHON=python
export GRASS_MESSAGE_FORMAT=silent
export GRASS_TRUECOLOR=TRUE
export GRASS_TRANSPARENT=TRUE
export GRASS_PNG_AUTO_WRITE=TRUE
# export GRASS_PNGFILE=map.bmp # uncomment to set '''GRASS_PNGFILE=map.bmp'''
# various PATHs
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export GRASS_LD_LIBRARY_PATH="$LD_LIBRARY_PATH"
export PYTHONPATH="$GISBASE/etc/python:$PYTHONPATH"
export MANPATH=$MANPATH:$GISBASE/man
# PID
export GIS_LOCK=$$
export GRASS_VERSION="6.4.0svn"
# lock...
tmp=/tmp/grass6-"`whoami`"-$GIS_LOCK
export GISRC="$tmp/gisrc"
mkdir "$tmp"
cp ~/.grassrc6 "$GISRC"
At the end of the ~/.bash_profile file, the following lines can be added to ensure no duplication of entries in the PATH variable
PATH=`awk -F: '{for(i=1;i<=NF;i++){if(!($i in a)){a[$i];printf s$i;s=":"}}}'<<<$PATH`
PYTHONPATH=`awk -F: '{for(i=1;i<=NF;i++){if(!($i in a)){a[$i];printf s$i;s=":"}}}'<<<$PYTHONPATH`
Important notes
Launching a grassXY session could still permit access on GRASS modules of the version that is set with the above script. The reason being is that grassXY scripts (e.g.: grass64, grass65, grass70) prepend the GRASS directories to PATH, LD_LIBRARY_PATH, etc. They won't remove any entries which are already there. A solution to this is to switch between GRASS versions by using a script like the following:
strippath()
{
(
oldpath="$1"
newpath=
IFS=:
for dir in $oldpath ; do
case "${dir}" in
*grass*)
;;
*)
newpath="$newpath:$dir"
;;
esac
done
echo "${newpath#:}"
)
}
PATH=`strippath $PATH`
export GISBASE=$PWD/dist.i686-pc-linux-gnu
export PATH="$GISBASE/bin:$GISBASE/scripts:$PATH"
export LD_LIBRARY_PATH="$GISBASE/lib"
export PYTHONPATH="$GISBASE/etc/python"
Note: the above script needs to be "source"d; executing it won't work. It might also require some adjustments (e.g. the GISBASE variable).
Using normal grass sessions commands are recorded in /grassdb/location/mapset/.bash_history. While working with "pure" bash, shell entries go in ~/.bash_history. Merging existing "grass-bash_history(-ies)" with the bash history log, would probably be not a good idea. Perhaps it is wise(r) to use normal GRASS sessions when working on real projects. Nevertheless, it is upon the users preferences and expertise level to decide what is best.
References
- Instructions and discussion on how to access GRASS mapsets outside of a GRASS session in the grass-user mailing list [1].
- removing duplicate entries in $PATH taken from [2]