INSTALL GRASS from source code
                   $Id$

Please read *all* text below.

Note: This version was previously called GRASS 5.1 and 5.7


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 source code (CVS or CVS snapshot)

  This version of source code can be acquired either from CVS
  repository (intevation.de:/grassrepository/grass51) 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


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       


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


RUNNING GRASS

Download a sample data package from the GRASS web site, for example
the Spearfish57 data set. Extract the data set and point GRASS in the
startup menu to the directory.

Enjoy.


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/grass57sourcecode/lives/
cvs update -dP
configure ...
make
make install


COMPILING INDIVIDUAL MODULES - OWN MODULES

Compiling own GRASS modules or modified modules:
Simply run "make" in the appropriate directory
and then install with "INST_NOW=y make".
It is not necessary to install the full distribution.
You may want to make an alias: alias gmake='INST_NOW=y make'

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
./doc/debugging.txt


SUPPORT

Note that this code is still somewhat experimental. Data formats and
functionality may change in future versions. DO NOT USE THIS VERSION
FOR PRODUCTION (ok, we do it...)!

If interested to develop GRASS, please join the GRASS developers 
mailing list:
http://grass.itc.it/devel/index.php


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/grass57/index.html#docs

Draft TUTORIAL

http://grass.itc.it/grass57/tutorial/index.html
http://grass.gdf-hannover.de/twiki/bin/view/GRASS/GrassSixTutorial

------------------
GRASS Development Team
$Date$