INSTALL GRASS 5.0 source code
($Id: INSTALL,v 1.22.2.3 2003/10/12 06:01:06 hamish Exp $)
Welcome to the GRASS GIS source code distribution. This is the installation
instruction file and contains the following sections:
INSTALLATION
CODE OPTIMIZATION
DEBUGGING OPTIONS
CONFIGURE OPTIONS
FILES TO CHECK
KNOWN EXCEPTIONS
CLEANING UP
COMPILING MODULES NOT COMPILED BY DEFAULT (INDIVIDUAL MODULES)
THINGS TO DO
UNINSTALLING GRASS
APPENDIX: LZW compression note
Please read through these sections before installing GRASS.
INSTALLATION
Before you compile GRASS, please read the file "REQUIREMENTS.html".
Note: If your system does not fulfill all requirements, some modules
won't be compiled (for example PostgresSQL or fftw, see section on
CONFIGURE OPTIONS). However, for the general usability of GRASS this
is no problem.
The intent of the install method is to have the following sequence
of commands work to install GRASS on any platform.
./configure
make
make install
The `configure' command (possibly with options; see below) should
identify all relevant system dependencies and create several files
(see below) containing dependency information. Eventually have a look
at
./configure --help
The `make' command will compile the sources in the current directory. Note
that you do not need root access to run `make', and in fact it is HIGHLY
recommended that you do not compile GRASS as the root user. At this point
you should be able to run grass by typing
bin.$ARCH/grass5
where $ARCH is a reference to your machine (eg mips-sgi-irix6.5 - is an
SGI machine running IRIX 6.5). Running `ls' will show you the appropriate
name for your system.
The `make install' command should install GRASS in the main filesystem. By
default, the majority of the GRASS files are stored under /usr/local/grass5,
while a few user executable files (eg. the GRASS executable) are stored
under /usr/local/bin. These directories are typically only writable by user
'root'. Thus, you will probably need to have root access if you use the
default locations.
If you want to change the default locations, use a sequence like this:
./configure --prefix=/opt/ --bindir=/local/grass/bin
make
make install
Here the default directories have been changed to /opt/grass5 for most of
the GRASS files, and /local/grass/bin for the executable files. If you had
not specified --bindir then the bindir would have been /opt/bin. See the
configure options below for more information.
At this point the system should be installed and ready to run by typing
grass5, with a few known exceptions (see below). If you identify problems
(e.g., system dependencies not already accounted for by `configure') please
pass along the relevant information (e.g., operating system, dependency
information, and ideally a fix) so the configuration system can be
fixed. Please see information about our bug report page at
http://grass.itc.it/grass5/index.html
If you want to catch the compiler output into a file, modify the above
"make" call. For sh or bash shells
make 2>&1 | tee compileOutput.log
For csh or tcsh shells
make | & tee compileOutput.log
The tee command sends output to both the terminal and the specified file
so you will still be able to see that GRASS is compiling.
The modules not being compiled due to errors will be listed in the file
error.log.
Note for Alpha64 users: Please read the ALPHA64/README.alpha64
and apply the 64bit patches.
CODE OPTIMIZATION
If you would like to set compiler optimisations, for a possibly faster
binary, type (don't enter a ";" anywhere):
CFLAGS=-O ./configure
or,
setenv CFLAGS -O
./configure
whichever works on your shell. Use -O2 instead of -O if your compiler
supports this (note: O is the letter, not zero). Using "gcc" compiler, you
can also specify processor specific flags (examples):
CFLAGS="-mcpu=k6 -O2" # AMD K6 processor
CFLAGS="-mcpu=pentium" # Intel Pentium processor
CFLAGS="-mcpu=pentiumpro" # Intel PentiumPro processor
To find out optional CFLAGS for your platform, enter:
gcc -dumpspecs
See also: http://gcc.gnu.org/
A real fast GRASS version (and small binaries) will be created with
LDFLAGS set to "stripping" (but this disables debugging):
CFLAGS="-O3 -mcpu=pentiumpro -Wall" LDFLAGS="-s" ./configure
DEBUGGING OPTIONS
The LDFLAGS="" must be undefined as "-s" will strip the debugging
information.
Don't use -O for CFLAGS if you want to be able to step through function
bodies. When optimisation is enabled, the compiler will re-order statements
and re-arrange expressions, resulting in object code which barely resembles
the source code.
See also the file
./documentation/debugging.txt
CONFIGURE OPTIONS
The `configure' script takes a number of options. Because it is
derived from the GNU autoconf system, `configure' accepts all the
normal options. The following lists a few that are relevant to GRASS.
--help lists all available options
--prefix=DIR install GRASS (except user
executable program) in DIR
--bindir=DIR install user executable
program in DIR
--with-includes=DIRS add DIRS to the compiler flags (-I)
--with-libs=DIRS add DIRS to the compiler flags (-L)
--with-tiff-includes=DIRS add DIRS to the compiler flags
(-I) for locating TIFF files
--with-tiff-libs=DIRS add DIRS to the compiler flags
(-L) for locating TIFF libraries
--with-tcltk-includes=DIRS add DIRS to the compiler flags
(-I) for locating Tcl/Tk files
--with-tcltk-libs=DIRS add DIRS to the compiler flags
(-L) for locating Tcl/Tk libraries
--without-PACKAGE do not use PACKAGE (same as
--with-PACKAGE=no)
--enable-sysv define the SYSV macro
--enable-termio define the USE_TERMIO macro
Note that DIRS can be a space separated list of directories enclosed in
double quotes. Note also that the last two options are needed only on a
few systems to account for system dependencies that are not yet included
within the `configure' script (see below). They will be removed in future
versions.
In general the configure options are organized as:
--with[out] controls the use of external features/libraries, while
--{en,dis}able controls the use of features provided by the package.
So, the following are controlled by --{en,dis}able:
--enable-sysv define the compiler macro SYSV
--enable-another-button use two-button mouse conveniently
--enable-socket use socket XDriver (default)
--enable-fifo use FIFO XDriver instead of sockets
--enable-w11 use W11 library for Windows X11 emulation
Everything else (i.e. library dependencies) uses
--with[out]-PACKAGE
Example: To disable PostgreSQL support you will specify
configure --without-postgres
GDAL note: If an argument is passed to --with-gdal, it should be the path
to the "gdal-config" script, e.g. "--with-gdal=/sw/bin/gdal-config".
Some packages may have identically named header files (config.h is
one common example). In such cases, you can ensure that the compiler
finds the right file by using a configuration option specific to that
package. Using
--with-postgres-includes=/usr/local/pgsql
would guarantee that the compiler uses postgresql's config.h in
/usr/local/pgsql, for example.
You can always see a full list of options to configure with
./configure --help
In case the include files are spreaded over two (or more) directories, you
may need to specify both, e.g.
--with-tcltk-includes='/usr/include/tcl8.3 /usr/include/tk8.3'
FILES TO CHECK
The `configure' script creates the following files to contain system
dependencies:
Makefile
src/CMD/head/head.$ARCH
src/include/config.h
$ARCH is a variable containing the host system (example:
head.i686-pc-linux-gnu).
After running `configure' it is wise to check these files to verify
that they contain the correct information. In particular, several
known exceptions (see below) might need fixing in src/CMD/head/head.$ARCH.
KNOWN EXCEPTIONS
Several known system dependencies are currently not handled
automatically by the `configure' script. Eventually these will be
fixed, especially if people with these systems can help (see below).
Scattered throughout the source code are dependencies on the C
preprocessor macro `SYSV'. Only `hpux10' machines need to define this
macro in src/CMD/head/head.$ARCH:
XLDFLAGS = -DSYSV
This is accomplished by the --enable-sysv option to `configure'.
CLEANING UP
There are five options for cleaning the GRASS source code. The first four
options are based on the GNU guidelines at:
http://www.gnu.org/manual/make-3.77/html_node/make_118.html
A fifth option is specific to the GRASS development project and does not
conform to the GNU standard. The sixth option allows you to uninstall the
installation files. Each option performs the following operations:
make mostlyclean - delete all object files, the next step file, and the
binary install script if it exists, keep the compiled
GRASS libraries - good for saving disk space
make clean - delete object files, next step file, libraries, and
generated directories like etc/ and dev/ - good for
recompiling on the same system (keep configure files)
make distclean - delete object files, next step file, libraries,
generated directories, head file, configure files,
and Makefile - good for starting the whole
installation from scratch
make maintainer-clean - delete object files, next step file, libraries,
generated directories, and generated lex/flex and
yacc/bison files - good for recompiling on the same
system and also generating the lex/flex and
yacc/bison files again
make savebinclean - delete object files, next step file, the binary
install script if it exists, libraries, head file,
configure files, and Makefile - good for deleting
everything but the binary files
make uninstall - deletes the installation files, by default
/usr/local/grass5, /usr/local/bin/grass5,
/usr/local/bin/gmake5, and
/usr/local/bin/gmakelinks5. This option does not
delete any files that were compiled only the
installation files. You may need root access for
this option.
COMPILING MODULES NOT COMPILED BY DEFAULT (INDIVIDUAL MODULES)
As part of the installation a general "gmake5" script is created in
/usr/local/bin (default) which allows you to compile modules separately.
To compile a single module go into the module's directory and compile it with:
gmake5
Then the module has to be linked to the GRASS front.end by:
gmakelinks5
Finally you have to install it:
a) either with a full installation:
cd root_of_grass_sources
make install
b) simplified you can also install just this module:
gmake5 -i
gmakelinks5 -i
Then you should be able to use the module. Note that gmakelinks5 only needs
to be run once after the module is compiled, but you always need to run the
make install procedure (full installation or using the "-i" flag).
This will be finally improved in GRASS 5.1.
If you never run "make install" then gmake5 and gmakelinks5 will be located
in the bin.$ARCH/ directory. Note that you will have to specify the absolute
path to these executables in order to run them. For example
/home/grass/bin.i686-pc-linux-gnu/gmake5
/home/grass/bin.i686-pc-linux-gnu/gmakelinks5
If you want to compile your own modules then please see the "SUBMITTING" file
for instructions regarding programming and submitting GRASS modules.
To save the gmake5/compiler related messages into a file, use the following
call for sh or bash shells:
gmake5 2>&1 | tee gmake5.log
or for csh or tcsh shells:
gmake5 | & tee gmake5.log
The tee command sends output to both the terminal and the specified file
so you will still be able to see the output of gmake5.
THINGS TO DO
A major task remaining is to replace the GISGEN system with a
proper set of Makefiles, all of which include a common one containing
the system dependencies (scheduled and started for GRASS 5.1).
GRASS 5.1 is in /grass51 in CVS.
UNINSTALLING GRASS
Uninstallation of GRASS binaries is pretty simple (example for installation
in /usr/local/grass5):
rm -rf /usr/local/grass5
rm -f /usr/local/bin/{grass5,gmake5,gmakelinks5}
should suffice.
APPENDIX: LZW compression note
(Jan 18 2001)
Because of the UNISYS patent on the LZW compression algorithm, GRASS 5
library code no longer uses this method to compress floating point
rasters and G3D files. Unfortunately, this creates an incompatible
change for persons using earlier versions of GRASS 5.0.
Note this DOES _NOT_ EFFECT CELL type rasters or persons just now upgrading
from GRASS 4.x. In order to make your data readable you *must*
uncompress all floating point rasters *before* installing newer GRASS
libraries and binaries. The command "r.compress -u" will do the job.
After installing the new binaries you may recompress your rasters
with "r.compress" which will use the DEFLATE method availabe in libz.
Unfortunately, any LZW compressed G3D files must be dumped with
r3.out.ascii, and then reimported.
The GRASS 5.0 team apologizes for this inconvenience. See also:
http://grass.itc.it/announces/announce_lzw_removal.html
GRASS Development Team
$Date: 2003/10/12 06:01:06 $
