diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 5be251d5489..00000000000 --- a/INSTALL +++ /dev/null @@ -1,319 +0,0 @@ - INSTALL GRASS from source code - ------------------------------ - -Please read *all* text below. - -Table of contents -PREREQUISITES -(A) SOURCE CODE DISTRIBUTION -(B) COMPILATION -(C) COMPILATION NOTES for 64bit platforms -(D) INSTALLATION (first time) -(E) INSTALLATION ON MACOSX -(F) RUNNING GRASS -(G) UPDATE OF SOURCE CODE -(H) COMPILING INDIVIDUAL MODULES - OWN MODULES -(I) CODE OPTIMIZATION -(J) DEBUGGING OPTIONS -(K) LARGE FILE SUPPORT (for raster maps) -(L) SUPPORT -(M) GRASS GIS PROGRAMMER'S MANUAL -(N) CONTRIBUTING CODE AND PATCHES -(O) DRAFT TUTORIAL - - -PREREQUISITES - -The install order matters. GRASS needs at least two libraries -which have to be installed before installing/compiling GRASS: -For links to the software, see ./REQUIREMENTS.html in this -directory: - -Installation order: - 1. PROJ - 2. GDAL-OGR (compiled without GRASS support) - 3. optionally: databases such as PostgreSQL, MySQL, sqlite - 4. GRASS GIS - 5. optionally: GDAL-OGR-GRASS plugin - -(A) SOURCE CODE DISTRIBUTION - -GRASS source code is currently distributed in 2 forms: - -1) Officially released source code (e.g. grass-8.2.0.tar.gz or later) - - 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. 8.2.0, 8.2.1 - etc. See - https://github.com/OSGeo/grass/releases - -2) Snapshots of source code (generated from GitHub) - - This version of the source code can be acquired either from the GitHub - repository (https://github.com/OSGeo/grass/) or as a auto-generated snapshot - (*.tar.gz package) of the GitHub repository. The snapshot name - contains the date when the snapshot was created (checked out from - the GitHub repository), e.g. grass-8.2.git_src_snapshot_2022_04_27.tar.gz - from https://grass.osgeo.org/grass-devel/source/snapshot/ - Further instructions at https://trac.osgeo.org/grass/wiki/DownloadSource - - -(B) COMPILATION - -IMPORTANT: All Unix based distributions are different. - For Solaris, see hints below. - -The command, - - ./configure --help - -explains the options used to disable the compilation of non-mandatory -GRASS modules. See REQUIREMENTS.html for details on dependencies. -Detailed Wiki notes for various operating systems (MS-Windows, GNU/Linux -distributions, FreeBSD, AIX, etc) are available at: -https://grasswiki.osgeo.org/wiki/Compile_and_Install - -First step of the compilation (-g for debugging, or -O2 for optimization): - - 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 as HTML files - make packagehtmldocs - package programmer's documentation in HTML - make pdfdocs - generate programmer's documentation as PDF files - - -Next step is the compilation itself: - - make - -Note for Solaris users (see also Wiki page above): - -To configure GRASS correctly on a system which doesn't have a suitable -install program (AC_PROG_INSTALL ignores versions which are known to -have problems), you need to ensure that $srcdir is an absolute path, -by using e.g.: - - `pwd`/configure ... -or: - ./configure --srcdir=`pwd` ... - -Then proceed as described above. - - -Note when using a compiler different from "gcc": - -By setting environment variables, the compiler -names can be defined (C and C++): - - CC=cc CPP=cpp ./configure ... - - -(C) COMPILATION NOTES for 64bit platforms - -To successfully compile GRASS on 64bit platforms, the required -FFTW2 library has to be compiled with -fPIC flag: - - #this applies to FFTW3, not to GRASS GIS: - cd fftw-3.3.4/ - 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 \ - ... - -See also CODE OPTIMIZATION below. - - -(D) INSTALLATION (first time) - -After compilation, the resulting code is stored in the directory - ./dist.$ARCH -and the scripts (grass, ...) in - ./bin.$ARCH - -To run GRASS, simply start - ./bin.$ARCH/grass - -or run - - make install - grass - - -(E) INSTALLATION ON MACOSX - -See the ReadMe.rtf in the ./macosx/ folder and the Wiki page above. - - -(F) RUNNING GRASS GIS - -Download a sample data package from the GRASS web site, see -https://grass.osgeo.org/download/sample-data/ - -Extract the data set and point the "Database" field in the -GRASS GIS startup menu to the extracted directory. - -Enjoy. - - -(G) UPDATE OF SOURCE CODE - -Assuming that you want to update your current installation from -GitHub, you have to perform a few steps. In general: - -- update from GitHub -- configure, compile - -In detail: - - cd /where/your/grass-source-code/lives/ - git fetch --all - git merge upstream/main - ./configure ... - make - make install - -For details, see https://trac.osgeo.org/grass/wiki/HowToGit - -(H) 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 gmake='INST_NOW=y make' -Then simply compile/install the current module with - gmake - -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). - - -(I) 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, please suggest -better settings to us): - - CFLAGS="-mcpu=athlon -O2" # AMD Athlon processor with code optimisations - CFLAGS="-mcpu=pentium" # Intel Pentium processor - CFLAGS="-mcpu=pentium4" # Intel Pentium4 processor - CFLAGS="-O2 -msse -msse2 -mfpmath=sse -minline-all-stringops" # Intel XEON 64bit processor - CFLAGS="-mtune=nocona -m64 -minline-all-stringops" # Intel Pentium 64bit processor - -Note: As of version 4.3.0, GCC offers the -march=native switch that -enables CPU auto-detection and automatically selects optimizations supported -by the local machine at GCC runtime including -mtune. - -To find out optional CFLAGS for your platform, enter: - gcc -dumpspecs - -See also: https://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= -Wall" LDFLAGS="-s" ./configure - - -(J) 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 and the Wiki page -https://grasswiki.osgeo.org/wiki/GRASS_Debugging - - -(K) LARGE FILE SUPPORT (for raster maps) - -GRASS GIS includes improved support for reading and writing large files -(> 2GB) if it is possible in your operating system. If you compile with - configure [...] --enable-largefile -you should be able to have raster and vector maps which are larger than 2GB. - -While most code has been updated, individual programs may not yet work with -large files - please report. - -See also -https://grasswiki.osgeo.org/wiki/GRASS_GIS_Performance -https://grasswiki.osgeo.org/wiki/Software_requirements_specification - -(L) 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 https://grass.osgeo.org/contribute/ - -If you are interested in helping to develop GRASS, please join the GRASS -developers mailing list. See https://grass.osgeo.org/development/ - - -(M) 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: -https://grass.osgeo.org/programming8/ - -(N) CONTRIBUTING CODE AND PATCHES - -Please see ./SUBMITTING in this directory, or better, -https://trac.osgeo.org/grass/wiki/Submitting - - -(O) TUTORIALS - -https://grass.osgeo.org/learn/newcomers/ - ------------------- -(C) 1999-2022 by The GRASS Development Team diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000000..aff515781dd --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,371 @@ +# Install GRASS GIS from source code + +Please read _all_ text below. + +## Table of contents + +- PREREQUISITES +- (A) SOURCE CODE DISTRIBUTION +- (B) COMPILATION +- (C) COMPILATION NOTES for 64bit platforms +- (D) INSTALLATION (first time) +- (E) INSTALLATION ON MACOSX +- (F) RUNNING GRASS +- (G) UPDATE OF SOURCE CODE +- (H) COMPILING INDIVIDUAL MODULES - OWN MODULES +- (I) CODE OPTIMIZATION +- (J) DEBUGGING OPTIONS +- (K) LARGE FILE SUPPORT (for raster maps) +- (L) SUPPORT +- (M) GRASS GIS PROGRAMMER'S MANUAL +- (N) CONTRIBUTING CODE AND PATCHES +- (O) DRAFT TUTORIAL + +## PREREQUISITES + +The install order matters. GRASS needs at least two libraries +which have to be installed before installing/compiling GRASS: +For links to the software, see ./REQUIREMENTS.html in this +directory: + +Installation order: + +1. PROJ +2. GDAL-OGR (compiled without GRASS support) +3. optionally: databases such as PostgreSQL, MySQL, sqlite +4. GRASS GIS +5. optionally: GDAL-OGR-GRASS plugin + +## (A) SOURCE CODE DISTRIBUTION + +GRASS source code is currently distributed in 2 forms: + +### Officially released source code + +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. 3.7.0, 3.7.1 +etc. See +. + +### Snapshots of source code (generated from GitHub) + +This version of the source code can be acquired either from the GitHub +repository () or as a auto-generated snapshot +(`*.tar.gz` package) of the GitHub repository. The snapshot name +contains the date when the snapshot was created (checked out from +the GitHub repository), e.g. grass-3.7.git_src_snapshot_2022_04_27.tar.gz +from +Further instructions at + +## (B) COMPILATION + +IMPORTANT: All Unix based distributions are different. +For Solaris, see hints below. + +The command, + +``` +./configure --help +``` + +explains the options used to disable the compilation of non-mandatory +GRASS modules. See REQUIREMENTS.html for details on dependencies. +Detailed Wiki notes for various operating systems (MS-Windows, GNU/Linux +distributions, FreeBSD, AIX, etc) are available at: + + +First step of the compilation (-g for debugging, or -O2 for optimization): + +``` +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 as HTML files +make packagehtmldocs - package programmer's documentation in HTML +make pdfdocs - generate programmer's documentation as PDF files +``` + +Next step is the compilation itself: + +``` +make +``` + +Note for Solaris users (see also Wiki page above): + +To configure GRASS correctly on a system which doesn't have a suitable +install program (AC_PROG_INSTALL ignores versions which are known to +have problems), you need to ensure that $srcdir is an absolute path, +by using e.g.: + +``` +`pwd`/configure ... +``` + +or: + +``` +./configure --srcdir=`pwd` ... +``` + +Then proceed as described above. + +Note when using a compiler different from "gcc": + +By setting environment variables, the compiler +names can be defined (C and C++): + +``` +CC=cc CPP=cpp ./configure ... +``` + +## (C) COMPILATION NOTES for 64bit platforms + +To successfully compile GRASS on 64bit platforms, the required +FFTW2 library has to be compiled with -fPIC flag: + +``` +#this applies to FFTW3, not to GRASS GIS: +cd fftw-3.3.4/ +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 \ + ... +``` + +See also CODE OPTIMIZATION below. + +## (D) INSTALLATION (first time) + +After compilation, the resulting code is stored in the directory + +``` +./dist.$ARCH +``` + +and the scripts (grass, ...) in + +``` +./bin.$ARCH +``` + +To run GRASS, simply start + +``` +./bin.$ARCH/grass +``` + +or run + +``` +make install +grass +``` + +## (E) INSTALLATION ON MACOSX + +See the ReadMe.rtf in the ./macosx/ folder and the Wiki page above. + +## (F) RUNNING GRASS GIS + +Download a sample data package from the GRASS web site, see + + +Extract the data set and point the "Database" field in the +GRASS GIS startup menu to the extracted directory. + +Enjoy. + +## (G) UPDATE OF SOURCE CODE + +Assuming that you want to update your current installation from +GitHub, you have to perform a few steps. In general: + +- update from GitHub +- configure, compile + +In detail: + +``` +cd /where/your/grass-source-code/lives/ +git fetch --all +git merge upstream/main +./configure ... +make +make install +``` + +For details, see + +## (H) 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 gmake='INST_NOW=y make' +``` + +Then simply compile/install the current module with + +``` +gmake +``` + +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). + +## (I) 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, please suggest +better settings to us): + +``` +CFLAGS="-mcpu=athlon -O2" # AMD Athlon processor with code optimisations +CFLAGS="-mcpu=pentium" # Intel Pentium processor +CFLAGS="-mcpu=pentium4" # Intel Pentium4 processor +CFLAGS="-O2 -msse -msse2 -mfpmath=sse -minline-all-stringops" # Intel XEON 64bit processor +CFLAGS="-mtune=nocona -m64 -minline-all-stringops" # Intel Pentium 64bit processor +``` + +Note: As of version 4.3.0, GCC offers the -march=native switch that +enables CPU auto-detection and automatically selects optimizations supported +by the local machine at GCC runtime including -mtune. + +To find out optional CFLAGS for your platform, enter: + +``` +gcc -dumpspecs +``` + +See also: + +A real fast GRASS version (and small binaries) will be created with +LDFLAGS set to "stripping" (but this disables debugging): + +``` +CFLAGS="-O2 -mcpu= -Wall" LDFLAGS="-s" ./configure +``` + +## (J) 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 and the Wiki page + + +## (K) LARGE FILE SUPPORT (for raster maps) + +GRASS GIS includes improved support for reading and writing large files +(> 2GB) if it is possible in your operating system. If you compile with + +``` +configure [...] --enable-largefile +``` + +you should be able to have raster and vector maps which are larger than 2GB. + +While most code has been updated, individual programs may not yet work with +large files - please report. + +See also + + + +## (L) 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 + +If you are interested in helping to develop GRASS, please join the GRASS +developers mailing list. See + +## (M) 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: + + +## (N) CONTRIBUTING CODE AND PATCHES + +Please see ./SUBMITTING in this directory, or better, + + +## (O) TUTORIALS + + + +## Authors + +Markus Neteler and the GRASS Development Team diff --git a/Makefile b/Makefile index fbfce0df52d..d77cb018e11 100644 --- a/Makefile +++ b/Makefile @@ -8,8 +8,8 @@ # Radim Blazek - Italy - blazek AT itc.it # PURPOSE: It provides the commands necessary to compile, install, # clean, and uninstall GRASS -# See INSTALL file for explanations. -# COPYRIGHT: (C) 2002-2012 by the GRASS Development Team +# See INSTALL.md file for usage. +# COPYRIGHT: (C) 2002-2022 by the GRASS Development Team # # This program is free software under the GNU General Public # License (>=v2). Read the file COPYING that comes with GRASS @@ -51,7 +51,7 @@ DIRS = \ SUBDIRS = $(DIRS) -FILES = AUTHORS CHANGES CITING COPYING GPL.TXT INSTALL REQUIREMENTS.html contributors.csv contributors_extra.csv translators.csv +FILES = AUTHORS CHANGES CITING COPYING GPL.TXT INSTALL.md REQUIREMENTS.html contributors.csv contributors_extra.csv translators.csv FILES_DST = $(patsubst %,$(ARCH_DISTDIR)/%,$(FILES)) default: diff --git a/README.md b/README.md index f502017e3cf..5b509155832 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,9 @@ Want to become a core developer? See ## How to compile GRASS -> See INSTALL file. +> See the INSTALL.md file. -Yes, you should really read [INSTALL](INSTALL). In addition, there are detailed [compile instructions](https://grasswiki.osgeo.org/wiki/Compile_and_Install) in the Wiki. +Yes, you should really read [INSTALL.md](INSTALL.md). In addition, there are detailed [compile instructions](https://grasswiki.osgeo.org/wiki/Compile_and_Install) in the Wiki. ## Docker diff --git a/REQUIREMENTS.html b/REQUIREMENTS.html index 8fe03058aca..e22ac0837d1 100644 --- a/REQUIREMENTS.html +++ b/REQUIREMENTS.html @@ -18,7 +18,7 @@

REQUIREMENTS to compile GRASS GIS 8

depending on your platform and compiler flags. During a full compilation you may need temporarily up to 550MB including the source code.

-To enable and disable features please read the INSTALL file. +To enable and disable features please read the INSTALL.md file.

General requirements:

diff --git a/doc/debugging.txt b/doc/debugging.txt index 3e6fac02e0d..797ff5ff853 100644 --- a/doc/debugging.txt +++ b/doc/debugging.txt @@ -27,7 +27,7 @@ Further hints: ---------------------------------------------------- To make gcc less tolerant in accepting errors and code flaws, compile -with (see also ../INSTALL): +with (see also the INSTALL.md file): export CFLAGS='-g -ansi -Wall -D_BSD_SOURCE=1 -D_SVID_SOURCE=1 -D_POSIX_SOURCE=1 -D_POSIX_C_SOURCE=199506L' diff --git a/doc/howto_release.md b/doc/howto_release.md index e85d69fb9c4..4856d53b1d8 100644 --- a/doc/howto_release.md +++ b/doc/howto_release.md @@ -305,10 +305,10 @@ echo $SERVER2:$SERVER2DIR # upload along with associated files: scp -p grass-$VERSION.* AUTHORS COPYING ChangeLog_$VERSION.gz \ - INSTALL REQUIREMENTS.html CONTRIBUTING.md $USER@$SERVER1:$SERVER1DIR + INSTALL.md REQUIREMENTS.html CONTRIBUTING.md $USER@$SERVER1:$SERVER1DIR scp -p grass-$VERSION.* AUTHORS COPYING ChangeLog_$VERSION.gz \ - INSTALL REQUIREMENTS.html CONTRIBUTING.md $USER@$SERVER2:$SERVER2DIR + INSTALL.md REQUIREMENTS.html CONTRIBUTING.md $USER@$SERVER2:$SERVER2DIR # Only at full release (i.e., not for RCs)! # generate link to "latest" source code diff --git a/macosx/ReadMe.md b/macosx/ReadMe.md index 33eb84d6e23..2a71608c552 100644 --- a/macosx/ReadMe.md +++ b/macosx/ReadMe.md @@ -44,7 +44,7 @@ init.sh. ## Building GRASS Building GRASS as a Mac OS X application is pretty much the same as for -a unix build (see the [INSTALL](../INSTALL) document for details). For an +a unix build (see the [INSTALL.md](../INSTALL.md) document for details). For an application, just add this option to configure: `--enable-macosx-app`