INSTALL GRASS 5.0 source code ($Id: INSTALL,v 1.22.2.1 2002-06-16 15:29:17 glynn 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 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 fullfil 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": CFLAGS="-O3 -mcpu=pentiumpro -Wall" LDFLAGS="-s" ./configure 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: 2002-06-16 15:29:17 $