GRASS GIS 8 Programmer's Manual
8.2.2dev(2023)-3d2c704037
|
GRASS GIS (Geographic Resources Analysis Support System) is an open source, free software Geographical Information System (GIS) with raster, topological vector, image processing, and graphics production functionality that operates on various platforms through a graphical user interface (GUI) or command line interface (CLI). It is released under GNU General Public License (GPL).
This manual introduces the reader to the Geographic Resources Analysis Support System from the programming perspective. Design theory, system support libraries, system maintenance, and system enhancement are all presented. This work is part of ongoing research being performed by the GRASS Development Team, an international team of programmers, GRASS module authors are cited within their module's source code and the contributed manual pages.
© 2000-2023 by the GRASS Development Team
This manual is published under GNU Free Documentation License (GFDL), and comes with ABSOLUTELY NO WARRANTY. The development of GRASS software and this manual is kindly supported by the Open Source Geospatial Foundation, who provides the GRASS main infrastructure.
Main web site: https://grass.osgeo.org
Note: Missing entries below still need to be documented in Doxygen format.
(the name refers to the directory name in lib/
in the source code)
(the name refers to the directory name in lib/
in the source code)
A GRASS raster map consists of several files in several subdirectories in a mapset, organized as follows:
A GRASS vector maps are stored in several separate files in a single directory (see GRASS Vector Library). While the attributes are stored in either a DBF file, a SQLite file or in an external DBMS (PostgreSQL, MySQL, ODBC), the geometric data are saved as follows:
GRASS modules are compiled and installed using the UNIX make
command, which reads a file named Makefile
(see Multiple-Architecture Conventions for more information) and then runs the compiler. The GRASS compilation process allows for multiple-architecture compilation from a single copy of the source code (for instance, if the source code is NFS mounted to various machines with differing architectures). This chapter assumes that the programmer is familiar with make
and its accompanying Makefile.
To compile enter following:
./configure make make install
Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The start script "grass7x" will be placed into "/usr/local/bin/".
Optionally other target directories can be specified while "configuring":
./configure --prefix=/opt/grass-7.x.y --with-bindir=/usr/bin make make install
This will store the GRASS binaries into the directory "/opt/grass-7.x.y" and the script mentioned above into "/usr/bin".
The script "make" is required to compile single modules. The compilation process and requirements are discussed in more detail now.
GRASS Libraries. The following variables name the various GRASS libraries:
UNIX Libraries: The following variables name some useful UNIX system libraries:
Compiler and loader variables. The following variables are related to compiling and loading C programs:
$CFLAGS
. It has no predefined values. It is usually used to specify additional -I include directories, or -D preprocessor defines.The complete syntax for a Makefile is discussed in the UNIX documentation for make
and will not be repeated here. The essential idea is that a target (e.g. a GRASS module) is to be built from a list of dependencies (e.g. object files, libraries, etc.). The relationship between the target, its dependencies, and the rules for constructing the target is expressed according to the following syntax:
If the target does not exist, or if any of the dependencies have a newer date than the target (i.e., have changed), the actions will be executed to build the target. The actions must be indented using a TAB. make
is picky about this. It does not like spaces in place of the TAB.
The following conventions allow for multiple architecture compilation on a machine that uses a common or networked GRASS source code directory tree.
Object files and library archives are compiled into subdirectories that represent the architecture that they were compiled on. These subdirectories are created in the $SRC directory as OBJ.arch
and LIB.arch
, where arch
represents the architecture of the compiling machine. Thus, for example, $SRC/OBJ.sun4 would contain the object files for Sun/4 and SPARC architectures, and $SRC/LIB.686-pc-linux-gnu
would contain library archives for Linux architectures. Likewise, $SRC/OBJ.686-pc-linux-gnu
would contain the object files for Linux architectures, and $SRC/LIB.686-pc-linux-gnu
would contain library archives for Linux architectures.
Note that 'arch' is defined for a specific architecture during setup and compilation of GRASS, it is not limited to sun4 or any specific string.
A module is a GRASS command invoked by the user.
Each module which modifies and writes data must read from input and write to output so that data may not be lost. For example v.spag
works on map at in GRASS GIS 5.0 but if program (system) crashes or threshold was specified incorrectly and vector was not backuped, data were lost. In this case map option should be replaced by input and output.
Topology is always built by default if the coor file was modified.
Dimensionality is generally kept. Input 2D vector is written as 2D, 3D as 3D. There are a few modules which change the dimension on purpose.
Flags:
Parameters: