Run GRASS interface in an R session not started within GRASS. In general, most users will use
initGRASS in throwaway locations, to use GRASS modules on R objects without the need to define and populate a location. The function initializes environment variables used by GRASS, the .gisrc used by GRASS for further environment variables, and a temporary location.
On Windows, if OSGeo4W GRASS is being used, the R session must be started in the OSGeo4W shell. If not, the non-standard placing of files and of environment variables confuses the function. If
toupper(gisBase) contains “OSGEO4W64/APPS/GRASS” or “OSGEO4W/APPS/GRASS” (and after converting “\” to “/”), but the environment variable
OSGEO4W_ROOT is not defined,
initGRASS() will exit with an error before confusion leads to further errors. For further details, see https://github.com/rsbivand/rgrass7/issues/16 and https://lists.osgeo.org/pipermail/grass-stats/2018-November/001800.html.
The locking functions are used internally, but are exposed for experienced R/GRASS scripters needing to use the GRASS module “g.mapset” through
initGRASS in an existing GRASS location. In particular, “g.mapset” may leave a
.gislock file in the current MAPSET, so it may be important to call
unlink_.gislock to clean up before quitting the R session.
remove_GISRC may be used to try to remove the file given in the “GISRC” environment variable if created by
initGRASS with argument
initGRASS(gisBase, home, SG, gisDbase, addon_base, location, mapset, override = FALSE, use_g.dirseps.exe = TRUE, pid, remove_GISRC=FALSE) get.GIS_LOCK() set.GIS_LOCK(pid) unset.GIS_LOCK() unlink_.gislock() remove_GISRC()
The directory path to GRASS binaries and libraries, containing bin and lib subdirectories among others
The directory in which to create the .gisrc file; defaults to
if missing, assumed to be “$HOME/.grass7/addons” on Unix-like platforms, on MS Windows “%APPDATA%\GRASS7\addons”, and checked for existence
default FALSE, set to TRUE if accidental trashing of GRASS .gisrc files and locations is not a problem
default TRUE; when TRUE appears to work for WinGRASS Native binaries, when FALSE for QGIS GRASS binaries; ignored on other platforms.
default FALSE; if TRUE, attempt to unlink the temporary file named in the “GISRC” environment variable when the R session terminates or when this package is unloaded
The function establishes an out-of-GRASS working environment providing GRASS commands with the environment variable support required, and may also provide a temporary location for use until the end of the running R session if the
home argument is set to
tempdir(), and the
gisDbase argument is not given. Running
gmeta6 shows where the location is, should it be desired to archive it before leaving R.
The function runs
gmeta6 before returning the current values of the running GRASS session that it provides.
If any package command fails with a UTF-8 error from the XML package, try using
setXMLencoding to work around the problem that GRASS modules declare --interface-description output as UTF-8 without ensuring that it is (French is of 6.4.0 RC5 latin1).
Roger S. Bivand, e-mail: Roger.Bivand@nhh.no