INSTALL GRASS 5.0 source code ($Id: INSTALL,v 1.19.2.6 2001-05-11 05:20:03 justin Exp $) Welcome to the GRASS GIS source code distribution. This is the installation instruction file and contains the following sections: INSTALLATION CODE OPTIMIZATION CONFIGURE OPTIONS FILES TO CHECK KNOWN EXCEPTIONS CLEANING UP COMPILING MODULES NOT COMPILED BY DEFAULT (INDIVIDUAL MODULES) THINGS TO DO Please read through these sections before installing GRASS. ************ IMPORTANT READ THIS ********************************* 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://www.geog.uni-hannover.de/grass/announces/announce_lzw_removal.html ******************************************************************* INSTALLATION Before you compile GRASS, please read the file REQUIREMENTS. Note: If your system does not fullfil all requirements, some modules won't be compiled. The intent of the new 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. 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://www.geog.uni-hannover.de/grass/grass5/index.html If you want to catch the compiler output into a file, modify the above "make" call for sh or bash shells to make 2>&1 | tee compileOutput.log or for csh or tcsh shells to 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 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. 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/ 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) --with-SYSV define the SYSV macro --with-USE_TERMIO define the USE_TERMIO macro Note that DIRS can be a space separated list of directories. 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. To disable the support of a specific package you can use the --without-PACKAGE option. Example: To disable PostgreSQL support you will specify configure --without-postgresql 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 --with-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. 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: gmake5 > gmake5.out 2>&1 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 for GRASS 5.1). GRASS Development Team $Date: 2001-05-11 05:20:03 $