INSTALL GRASS from source code
$Id: INSTALL,v 1.27.2.3 2006/02/16 20:05:07 markus Exp $
Please read *all* text below.
Note: During the development stages, this version of GRASS was
previously called GRASS 5.1 and 5.7.
Table of contents
(A) SOURCE CODE DISTRIBUTION
(B) COMPILATION
(C) COMPILATION NOTES for 64bit platforms
(D) INSTALLATION (first time)
(E) RUNNING GRASS
(F) UPDATE OF SOURCE CODE (CVS or CVS snapshot only)
(G) COMPILING INDIVIDUAL MODULES - OWN MODULES
(H) CODE OPTIMIZATION
(I) DEBUGGING OPTIONS
(J) SUPPORT
(K) GRASS PROGRAMMER'S MANUAL
(L) DRAFT TUTORIAL
(A) SOURCE CODE DISTRIBUTION
GRASS source code is currently distributed in 2 forms:
1) Officially released source code (e.g. grass-6.0.0.tar.gz)
The Full source code version contains all the GRASS source code
required for compilation. It is distributed as one file (*.tar.gz
package) and the version is composed of 3 numbers, e.g. 6.0.0, 6.0.1
etc.
2) CVS or CVS Snapshots of source code (CVS or CVS snapshot)
This version of the source code can be acquired either from the CVS
repository (intevation.de:/grassrepository/grass6) or as a snapshot
(*.tar.gz package) of that CVS repository. The CVS snapshot name
contains the date when the snapshot was created (checked out from
the CVS repository), e.g. grass61src_cvs_snapshot_exp_2005_03_19.tar.gz
(B) COMPILATION
IMPORTANT: All unix distributions are different. The command,
./configure --help
explains the options used to disable the compilation of non-mandatory
GRASS modules. See REQUIREMENTS.html for details.
First step of the compilation:
CFLAGS="-g -Wall" ./configure
Explanation of make targets:
make install - installs the binary
make bindist - make a binary package with install script
make srcdist - make a source package for distribution
make srclibsdist - make a source package for library distribution
make libs - make libraries only
make clean - delete all files created by 'make'
make distclean - 'make clean' + delete all files created by './configure'
make libsclean - clean libraries compiled by 'make libs'
make htmldocs - generate programmer's documentation in HTML
make packagehtmldocs - package programmer's documentation in HTML
make pdfdocs - generate programmer's documentation as PDF files
Next step is the compilation itself:
make
(C) COMPILATION NOTES for 64bit platforms
To successfully compile GRASS on 64bit platforms, the required
FFTW2 library has to be compiled with -fPIC flag:
#applies to FFTW2, not GRASS:
cd fftw-2.1.5/
CFLAGS="-fPIC" ./configure
make
make install
To fully enable 64bit library usage for GRASS on 64bit platforms,
the following additional parameters are recommended/required:
./configure \
--enable-64bit \
--with-libs=/usr/lib64 \
...
(D) INSTALLATION (first time)
After compilation, the resulting code is stored in the directory
./dist.$ARCH
and the scripts (grass6, ...) in
./bin.$ARCH
To run GRASS, simply start
./bin.$ARCH/grass6
or run
make install
grass6
(E) RUNNING GRASS
Download a sample data package from the GRASS web site, for example the
Spearfish60 data set. Extract the data set and point "database" in the
GRASS startup menu to the directory.
Enjoy.
(F) UPDATE OF SOURCE CODE (CVS or CVS snapshot only)
Assuming that you want to update your current installation from
CVS, you have to perform a few steps. In general:
- update from CVS
- configure, compile
In detail:
cd /where/your/grass6sourcecode/lives/
cvs update -dP
./configure ...
make
make install
(G) COMPILING INDIVIDUAL MODULES - OWN MODULES
To compile (self-made) GRASS modules or to compile modified modules
at least the GRASS libraries have to be compiled locally. This is
done by launching:
make libs
Then change into the module's directory and launch the "make"
command. The installation can be either done with "make install" from
the main source code directory or locally with
"INST_NOW=y make"
You may want to define an alias for this:
alias gmake6='INST_NOW=y make'
The simply compile/install the current module with
gmake6
Note: If you keep your module source code outside the standard GRASS
source code directory structure, you will have to change the relative
path(s) in the Makefile to absolute path(s).
(H) 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 the "gcc" compiler,
you can also specify processor specific flags (examples):
CFLAGS="-mcpu=athlon -O2" # AMD Athlon processor with code optimisations
CFLAGS="-mcpu=pentium" # Intel Pentium processor
CFLAGS="-mcpu=pentium4" # Intel Pentium4 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="-O2 -mcpu=pentium4 -Wall" LDFLAGS="-s" ./configure
(I) DEBUGGING OPTIONS
The LDFLAGS="" part 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.
The -g and -Wall compiler flags are often useful for assisting debugging:
CFLAGS="-g -Wall" ./configure
See also the file
./doc/debugging.txt
(J) SUPPORT
Note that this code is still actively being developed and errors inevitably
turn up. If you find a bug, please report it to the GRASS bug tracking system
so we can fix it. see http://grass.itc.it/bugtracking/bugreport.html
If you are interested in helping to develop GRASS, please join the GRASS
developers mailing list. see http://grass.itc.it/devel/index.php
(K) GRASS PROGRAMMER'S MANUAL
The Programmer's manual is generated with doxygen from the source code.
Please see the README file and the files at:
http://grass.itc.it/grass60/#docs
(L) DRAFT TUTORIAL
http://grass.itc.it/grass57/tutorial/index.html (outdated)
http://grass.gdf-hannover.de/twiki/bin/view/GRASS/GrassSixTutorial
------------------
GRASS Development Team
$Date: 2006/02/16 20:05:07 $
