                   INSTALL GRASS 5.0 source code

($Id: INSTALL,v 1.27.2.2 2004/10/31 20:07:51 paul Exp $)

Welcome to the GRASS GIS source code distribution. This is the installation
instruction file and contains the following sections:
    
    INSTALLATION
    STARTING GRASS
    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

Please read through these sections before installing GRASS.


INSTALLATION

Before you compile GRASS, please read the file "REQUIREMENTS.html". 
Note: Building of modules that depend on certain pre-requisite software
may be disabled by passing options to the configure script (for example 
PostgreSQL or fftw, see section on CONFIGURE OPTIONS). For general 
usability of GRASS, leaving out a few modules will often pose no problem.

This release of GRASS uses a new build system by default, known as 
the 'Alternate' build system. This uses separate build and source 
directories, i.e. you cannot run ./configure from the top-level source
directory. This is convenient when dealing with a project with such a 
large code base as GRASS. In addition the alternate build system allows
to compile the core GRASS libraries as shared, greatly reducing the 
size of the compiled binaries and install footprint.

The intent of the install method is to have the following sequence
of commands work to install GRASS on any platform.

	gunzip -fc grass-5.4.0.tar.gz | tar xvf -
	mkdir grass-build
	cd grass-build
	../grass-5.4.0/configure ... [system-specific options] ..
	make
	sudo make install

The `configure' command (almost always with options; see below) should
identify relevant system dependencies and create several files
(see below) containing dependency information. Make sure to read the 
output of
	./configure --help

In addition, for faster smaller binaries you may want to enable
optimisation and stripping. This may be done by, for example,

	CFLAGS=-O2 LDFLAGS=-s ../grass-5.4.0/configure ...

in Bourne or Bash shell or

	setenv CFLAGS -O2
	setenv LDFLAGS -s
	../grass-5.4.0/configure ...

in C shell. This should not be done if you need to debug the GRASS 
binaries. See section CODE OPTIMIZATION below for additional hints.

The `make' command will compile the sources in the current directory. Note
that you do not need root access to run `make'. If any compilation errors
are reported in individual modules you will need to check the output of
the make command to see what the error was. At this point
you should be able to run grass by typing

	./bin.$ARCH/grass54

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, all the GRASS files are stored under /usr/local/grass54 except
the start-up script grass54, which is stored in /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 start-up script. 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
grass54, 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.


STARTING GRASS

Ensure that the path to grass is in your PATH environment or
start grass with the full path name.  To start grass:
  grass54

Usage:
  grass54 [-h | -help | --help] [-text | -tcltk | -gui] [[[<GISDBASE>/]<LOCATION_NAME>/]<MAPSET>]

Flags:
  -h or -help or --help          print this help message
  -text                          use text based interface and set as default
  -tcltk or -gui                 use Tcl/Tk based graphical user interface
                                    and set as default
  [...]


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
	mk/vars.mk
	src/include/config.h

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 mk/vars.mk.


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/grass54, /usr/local/bin/grass54
			  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 "gmake54" script is created in
the build directory which allows you to compile modules separately.

To compile a single module go into the build directory and compile it with:

	./gmake54 path/to/module
e.g.    ./gmake54 src/raster/r.example

Then the module has to be linked to the GRASS front.end by:
  
   make links

Finally you have to install it:

a) either with a full installation:
   
   make install

Then you should be able to use the module. Note that make links only needs
to be run once after the module is compiled for the first time, but you 
need to run make install after each re-compile.

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 compiler output messages into a file, use the following
call for sh or bash shells:

	./gmake54 src/raster/r.example 2>&1 | tee make.log
	
or for csh or tcsh shells:

	./gmake54 src/raster/r.example | & tee make.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 make in the terminal window.


UNINSTALLING GRASS

Uninstallation of GRASS binaries is pretty simple (example for installation
in /usr/local/grass54):

	rm -rf /usr/local/grass54
	rm -f /usr/local/bin/grass54

should suffice.


$Date: 2004/10/31 20:07:51 $
