#LyX 1.4.4 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
\textclass article
\begin_preamble

\end_preamble
\language english
\inputencoding auto
\fontscheme pslatex
\graphics default
\paperfontsize 11
\spacing onehalf
\papersize a4paper
\use_geometry true
\use_amsmath 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\leftmargin 2cm
\topmargin 2.5cm
\rightmargin 2cm
\bottommargin 2.5cm
\secnumdepth 2
\tocdepth 2
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes true
\end_header

\begin_body

\begin_layout Title
GRASS Extensions Manager (GEM), Version 1.0.3
\newline
Manual
\end_layout

\begin_layout Author
Benjamin Ducke (benducke@compuserve.de)
\end_layout

\begin_layout Abstract
GRASS 6 Extensions Manager (GEM) is a small stand-alone program intended
 to make it easy for GRASS GIS users to download, compile and install additional
 GRASS modules.
 GEM manages source code, scripts and pre-compiled binaries in a simple
 file layout called an 
\emph on
extension
\emph default
.
 Extensions are accompanied by a set of ASCII files that store all relevant
 information including dependencies on other extensions or specific GRASS
 versions.
 Extensions can be stored conveniently in a single compressed archive file,
 a so-called 
\emph on
extension package
\emph default
 using external programs such as tar and gzip.
 An extension (package) can be created easily by copying existing source
 codes into the right places of a skeleton file layout and filling in some
 information in simple, commented ASCII files.
 Makefiles written for GRASS 6 should work with minimal changes as GEM uses
 a simplified version of the orginal GRASS make system.
\end_layout

\begin_layout Abstract
This Document provides instructions for using GEM and for writing portable
 GRASS extensions to be installed with GEM.
\begin_inset Note Note
status open

\begin_layout Standard
to produce one HTML page from this manual: use lyx to export to latex (plain)
 format; run latex 3 times on the exported .tex document to get references
 right; use latex2html: latex2html -split 0 -show_section_numbers GEM-Manual.tex
\end_layout

\begin_layout Standard
Clean up: rm *.dvi *.toc *.log *.aux *.tex
\end_layout

\begin_layout Standard
Note: since this does not get references within boxed text right, those
 references have been statically set in this document and may need to be
 adjusted should new sections be added!
\end_layout

\end_inset


\end_layout

\begin_layout Abstract

\newpage

\end_layout

\begin_layout Standard
\begin_inset LatexCommand \tableofcontents{}

\end_inset


\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Why Do I Need GEM?
\end_layout

\begin_layout Standard
GRASS GIS (
\begin_inset LatexCommand \htmlurl{www.grass.itc.it}

\end_inset

) is a powerful, modularized open source Geographic Information System.
 The base distribution comes with hundreds of useful modules.
 However, there are a few flaws in the design:
\end_layout

\begin_layout Enumerate
Installation of add-on modules that are not part of the main distribution
 (
\begin_inset LatexCommand \htmlurl{http://grass.gdf-hannover.de/twiki/bin/view/GRASS/GrassAddOns}

\end_inset

) is tedious.
 It requires a full copy of the GRASS source codes.
 Add-on sources must be copied to the right locations, compilation and installat
ion must then be started as though one was to install the whole system from
 scratch.
\end_layout

\begin_layout Enumerate
Users willing to install add-on functionality must have at least a basic
 knowledge of how to compile and install modules from C source code.
\end_layout

\begin_layout Enumerate
The sheer number of modules makes it hard to find the one that has exactly
 the functionality needed.
 There is no thematic grouping of modules.
 This becomes worse as more add-on modules are installed.
\end_layout

\begin_layout Enumerate
Developers of add-on functionality currently have no way to make this process
 more user-friendly.
 Add-on developers as a rule write modules that are functionaly closely
 related.
 These should be grouped and distributed as a package along with some over-archi
ng documentation to bind them together and make them more accessible from
 a user's perspective.
\end_layout

\begin_layout Enumerate
Some add-ons modules exist in the official CVS and in another place such
 as the developer's homepage.
 For a user, it is hard to know which version is more current.
 In fact, GRASS has no versioning scheme except for the base distribution
 itself.
\end_layout

\begin_layout Standard
GEM, the GRASS Extensions Manager, was developed as an open source solution
 to address all of these issues.
 It is a tool that simplifies development, distribution and installation
 of additional modules (extensions) for GRASS GIS (version 6.0 and above).
\end_layout

\begin_layout Standard
From the GRASS user's perspective GEM can be used to:
\end_layout

\begin_layout Itemize
Conveniently download and install add-on GRASS modules (extensions) that
 are not part of the CVS.
\end_layout

\begin_layout Itemize
Avoid having to keep a complete GRASS source tree on the disk for installing
 new functionality.
\end_layout

\begin_layout Itemize
Install add-on modules from provided binaries without the need to have any
 development tools installed.
\end_layout

\begin_layout Itemize
Manage installed extensions: query, update, uninstall them.
\end_layout

\begin_layout Standard
Form the GRASS developer's perspective GEM allows for:
\end_layout

\begin_layout Enumerate
Development of GRASS modules completely outside the CVS tree.
 In a dedicated directory that is much easier to maintain and sync.
\end_layout

\begin_layout Enumerate
Packaging of module source code, documentation and pre-compiled binaries
 and deployment as a single file (extension package).
\end_layout

\begin_layout Enumerate
Simple outsourcing of sets of GRASS functionality from the base distribution
 into extension packages.
\end_layout

\begin_layout Standard
GEM works on Linux/Unix, MacOS X and Win32 (Cygwin and MINGW) systems.
 There are some OS specific issues which are discussed in the appendix.
\end_layout

\begin_layout Section
How Does GEM Work?
\end_layout

\begin_layout Standard
The GEM program itself is a relatively simple frontend written in ANSI C
 that interacts with more complex installation scripts (make system) contained
 in each individual extension package.
 These scripts are a scaled-down and slightly modified version of the original
 GRASS 6 make system.
 Files in an extension package correspond 1:1 with the layout of the original
 GRASS source tree, the only difference being that an extension package
 only contains source code for the add-on modules plus a few things that
 are needed to setup the source code, parse HTML documentation etc.
\end_layout

\begin_layout Standard
A GRASS extension is essentially a minimal replication of the GRASS source
 tree including all necessary makefiles.
 It contains only the source code for a few modules that constitute the
 extensions.
 On the top level, you will find a number of ASCII files that contain the
 information gem needs to manage the extension.
 All information is managed in plain ASCII format.
 
\end_layout

\begin_layout Standard
Installed extensions will be registered in
\emph on
 $(PATH_TO_GRASS)/etc/extensions.db
\emph default
.
 This registry file also contains version and dependencies information.
 Each extension should also provide an uninstall script to be run when the
 user wants to get rid of that extension.
 
\end_layout

\begin_layout Standard
They are stored in 
\emph on
$(PATH_TO_GRASS)/etc/uninstall.<extension_name>
\emph default
.
 
\end_layout

\begin_layout Standard
Extension may add a submenu to the GIS Manager.
 The first extension installed creates an additional "Xtns" top level menu
 under which each extension can register a nested submenu.
 
\end_layout

\begin_layout Standard
Gem modifies $
\emph on
(PATH_TO_GRASS)/etc/d.m/menu.tcl
\emph default
 for this.
 
\end_layout

\begin_layout Standard
The extension source code is in the 
\emph on
src
\emph default
 directory, along with all the necessary makefiles.
 Other directories may hold pre-compiled binaries and should be named appropriat
ely (
\emph on
win32
\emph default
, 
\emph on
macosx
\emph default
, ...).
 
\end_layout

\begin_layout Standard
Extensions may provide code for C language modules and libraries, scripts
 and HTML documentation.
 
\end_layout

\begin_layout Standard
GEM compiles and install add-on modules using the sources and makefiles
 contained in the extension.
\end_layout

\begin_layout Standard
For the user, GEM is really simple to use.
 All that is required is a download of the extension package to install
 and knowledge of where the local GRASS installation resides.
 If the user does not have permission to install new files in the GRASS
 installation directory, a password for a user with sufficient permissions
 will be required (see next section).
\end_layout

\begin_layout Standard
Developers of add-on modules will (hopefully) also find the process of migrating
 their work to a GEM extension package a matter of minutes and well worth
 the effort.
 More information for developers can be found in section 
\begin_inset LatexCommand \ref{sec:Developing-Extensions-for}

\end_inset

 of this document.
\end_layout

\begin_layout Section
Installation and Usage
\end_layout

\begin_layout Standard
Note: in addition to GEM itself, you will probably want to install GNU C
 compiler and maketools for compilation.
 Tar, gzip, unzip, bunzip2 for handling various archive formats.
 Wget for fetching extensions from the internet.
 
\end_layout

\begin_layout Subsection
Program Installation
\begin_inset LatexCommand \label{sub:Program-Installation}

\end_inset


\end_layout

\begin_layout Standard
You can download GEM source code and binaries for several different platforms
 from the author's homepage (
\begin_inset LatexCommand \htmlurl{http://www.uni-kiel.de/ufg/index1.htm}

\end_inset

).
 Check the links at the bottom of the page.
 You will also find several extension packages for installation with GEM.
\end_layout

\begin_layout Standard
Download the file 
\emph on
gem-someversion.tar.gz
\emph default
 to a convenient location, unpack it and change into the newly created directory
:
\end_layout

\begin_layout LyX-Code
tar -xzvf gem-
\emph on
someversion
\emph default
.tar.gz
\end_layout

\begin_layout LyX-Code
cd gem-
\emph on
someversion
\end_layout

\begin_layout Standard
In this directory, you will find a folder 
\emph on
bin
\emph default
 that contains binaries for different platforms.
 Change into it and list its contents:
\end_layout

\begin_layout LyX-Code
cd bin
\end_layout

\begin_layout LyX-Code
ls
\end_layout

\begin_layout Standard
You will see a number of programs.
 Pick the one that corresponds to your OS and start it.
 E.g., if you are working in a cygwin environment under Windows, do:
\end_layout

\begin_layout LyX-Code
./gem-cygwin.exe
\end_layout

\begin_layout Standard
You should get a text explaining the program's options on your screeen.
\end_layout

\begin_layout Standard
If you want (and have the required permissions), you can copy the file to
 a directory for system-wide binaries so you can call GEM from anywhere
 without having to prefix a directory path (./ in the example above) by typing
 just 
\family typewriter
gem
\family default
:
\end_layout

\begin_layout LyX-Code
cp gem-cygwin.exe /usr/local/bin/gem
\end_layout

\begin_layout Standard
Once GEM has reached a stable release version (1.0), it will also become
 part of the GRASS CVS version.
 If you download and install such a version on your computer, you will automatic
ally have GEM available system-wide (usually 
\emph on
/usr/local/bin
\emph default
) and can just start it with:
\end_layout

\begin_layout LyX-Code
gem64
\end_layout

\begin_layout Standard
Instructions on how to user GEM to install an actual extension are given
 in section 
\begin_inset LatexCommand \ref{sub:Basic-Usage}

\end_inset

.
\end_layout

\begin_layout Subsection
Installation from Source Code
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 1
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: please make sure that you system-wide linker path includes the location
 of the GRASS dynamic libraries (e.g.
 
\emph on
/usr/local/grass-6.1.cvs/libs
\emph default
).
 This is usually done by adding an appropriate entry to 
\emph on
/etc/ld.so.conf
\emph default
 and running 
\emph on
ldconfig
\emph default
.
 You may have to consult your system's administrator.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You must have a C compiler, preferably GNU C, and the corresponding make
 tools installed.
 Most Linux/Unix systems should come with these installed.
 If not, use your distributions package manager to install them (look for
 something like 
\begin_inset Quotes eld
\end_inset

Development tools
\begin_inset Quotes erd
\end_inset

).
 Mac OS X and Cygwin users: see OS specific notes in section 
\begin_inset LatexCommand \ref{sec:OS-Specific-Issues}

\end_inset

.
\end_layout

\begin_layout Standard
Download the file 
\emph on
gem-someversion.tar.gz
\emph default
 to a convenient location, unpack it and change into the newly created directory
:
\end_layout

\begin_layout LyX-Code
tar -xzvf gem-
\emph on
someversion
\emph default
.tar.gz
\end_layout

\begin_layout LyX-Code
cd gem-
\emph on
someversion
\end_layout

\begin_layout Standard
In this directory, start the compilation process:
\end_layout

\begin_layout LyX-Code
make
\end_layout

\begin_layout Standard
Afer a few seconds, the compilation is done and you have an executable file
 that you can start from the current directory:
\end_layout

\begin_layout LyX-Code
./gem64
\end_layout

\begin_layout Standard
\SpecialChar \ldots{}
 or copy the executable to a system-wide directory, such as 
\emph on
/usr/local/bin
\emph default
.
\end_layout

\begin_layout Subsection
Quickstart
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 1
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: please be aware that GEM can only install modules in a specially prepared
 package.
 See section 4 for how to do this.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For the impatient.
 To install an extension into your running version of GRASS: start a GRASS
 session, download an extension and install it from inside the GRASS session
 using:
\end_layout

\begin_layout LyX-Code
gem64 --install=
\emph on
ExtensionName
\emph default
.tar.gz
\end_layout

\begin_layout Standard
You will now have to be patient as the extension is verified, configured
 and its source code compiled.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 1
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: if configuration fails, this is likely due to your operating system
 missing some external default software (such as the PostgreSQL database).
 You can use GEM's 
\begin_inset Quotes eld
\end_inset

--configure=
\begin_inset Quotes erd
\end_inset

 option to pass the same options that you passed to the GRASS configuration
 script (use quotation marks for more than one option), e.g.
 --configure='--with-nls --without-postgres' will configure the extension
 to use national language support but not try to find the PostgreSQL software.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To finish the installation, GEM needs to write the extension's new module
 files into the directory where GRASS has been installed.
 In many cases, this will be a system directory with restricted write access.
 Provide the superuser password if GEM asks you for it.
 Restart GIS Manager and look in the 
\begin_inset Quotes eld
\end_inset

Xtns
\begin_inset Quotes erd
\end_inset

 menu for new modules (some modules may not provide GIS Manager entries).
 If anything goes wrong or confuses you: read the rest of this section!
\end_layout

\begin_layout Subsection
Basic Usage
\begin_inset LatexCommand \label{sub:Basic-Usage}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 1
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: Operation of GEM under Cygwin is only possible in verbose mode (option
 
\begin_inset Quotes eld
\end_inset

-v
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

--verbose
\begin_inset Quotes erd
\end_inset

)! Please read section A.2 on Windows specific issues.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This section will show you how to use GEM to perform basic things: installing,
 querying and removing (un-installing) extensions for GRASS GIS.
 For the sake of simplicity, I will assume that your GRASS installation
 resides in 
\emph on
/usr/local/grass-6.0.0
\emph default
 and you may have to adjust this path in the examples below, so that it
 reflects your individual setup (Mac OS X users: see notes on system specific
 issues in section 
\begin_inset LatexCommand \ref{sub:Mac-OS-X}

\end_inset

 for how to find the path to your installation).
 Also, the extension package used in the following examples is called 
\emph on
RasterTools.tar.gz
\emph default
 and is in 
\begin_inset Quotes eld
\end_inset

tar'd gzip
\begin_inset Quotes erd
\end_inset

 format.
 Replace this with the name of the extension you wish to install as needed.
\end_layout

\begin_layout Standard
I will further assume that you (or your system's administrator) have copied
 the executable 
\emph on
gem64
\emph default
 into a directory from where it can be started system-wide (such as 
\emph on
/usr/local/bin
\emph default
) without having to prefix the path to the executable (see instructions
 in 
\begin_inset LatexCommand \ref{sub:Program-Installation}

\end_inset

).
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: in order to install extensions that do not provide binaries, you need
 to have a C compiler (preferably GNU CC) and make tools installed.
 Please refer to the OS specific section A for more details.
\end_layout

\begin_layout Standard
For unpacking extension packages you need the appropriate software.
 Depending on the format of the archive, this could be 
\emph on
tar
\emph default
, 
\emph on
gzip
\emph default
, 
\emph on
bunzip2
\emph default
 and 
\emph on
unzip
\emph default
.
\end_layout

\begin_layout Standard
If you want to get extensions from an internet source (http or ftp), you
 also need 
\emph on
wget
\emph default
.
 These programs will very likely already be installed on your system.
 If not, you will find it easy to locate a copy for your OS using an internet
 search engine.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
GEM understands short and long options.
 Long options are just a more legible version of the short options, which
 is why I will use them in this document.
 E.g.
 
\begin_inset Quotes eld
\end_inset

-i
\begin_inset Quotes erd
\end_inset

 is a short option that does exactly the same as 
\begin_inset Quotes eld
\end_inset

--install=
\begin_inset Quotes erd
\end_inset

.
 To see all options, short and long, simply call GEM without any options
 or 
\begin_inset Quotes eld
\end_inset

--help
\begin_inset Quotes erd
\end_inset

:
\end_layout

\begin_layout LyX-Code
gem64
\end_layout

\begin_layout Standard
The 
\begin_inset Quotes eld
\end_inset

--version
\begin_inset Quotes erd
\end_inset

 action shows information about the GEM version you are using.
\end_layout

\begin_layout Standard
You will notice that GEM knows a special sort of options called 
\begin_inset Quotes eld
\end_inset

actions
\begin_inset Quotes erd
\end_inset

 this are options that cause GEM to operate in some way on the extension.
 The regular 
\begin_inset Quotes eld
\end_inset

options
\begin_inset Quotes erd
\end_inset

 are just used to modify the way GEM works.
\end_layout

\begin_layout Standard
To install a module into your GRASS installation (in this example 
\emph on
/usr/local/grass-6.0.0
\emph default
), simply pass the name of the archive containing the extension or the directory
 with the unpacked files to the 
\begin_inset Quotes eld
\end_inset

--install=
\begin_inset Quotes erd
\end_inset

 action and supply the path to the GRASS installation for which you wish
 to install the extension (using the 
\begin_inset Quotes eld
\end_inset

--grass=
\begin_inset Quotes erd
\end_inset

 option): 
\end_layout

\begin_layout LyX-Code
gem64 --grass=/usr/local/grass-6.0.0 --install=RasterTools.tar.gz
\end_layout

\begin_layout Standard
If everything goes well, you will see a few messages on the screen and after
 a short while the program will inform you that it is done.
 If you do not have permission to write into the system-wide GRASS installation
 directory, you will be asked for the password of the user owning the GRASS
 binary files.
 
\end_layout

\begin_layout Standard
If any errors occur, use option 
\begin_inset Quotes eld
\end_inset

-v
\begin_inset Quotes erd
\end_inset

 (
\begin_inset Quotes eld
\end_inset

--verbose
\begin_inset Quotes erd
\end_inset

) to see what is going on.
 
\end_layout

\begin_layout Standard
By default, the 
\begin_inset Quotes eld
\end_inset

--install=
\begin_inset Quotes erd
\end_inset

 action performs an installation from source code.
 This will first configure the sources for your system's individual setup,
 then compile the source code into binaries, finally install them in the
 appropriate locations.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: an extension may also provide shell scripts that do not need to be
 compiled.
 Installation does, however, by default work in the same way.
 Look for the keyword 
\begin_inset Quotes eld
\end_inset

scripts
\begin_inset Quotes erd
\end_inset

 in the extension details (under 
\begin_inset Quotes eld
\end_inset

Binary installation files
\begin_inset Quotes erd
\end_inset

) by querying it as discussed in section 3.5 on installation of binaries.
 If it exists, you can perform a binary install (again, see section 3.5)
 for 
\begin_inset Quotes eld
\end_inset

scripts
\begin_inset Quotes erd
\end_inset

, skipping configuration and compilation steps and avoiding the need to
 have C development tools installed.
 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you invoke GEM from inside a running GRASS session, you can ommit the
 
\begin_inset Quotes eld
\end_inset

--grass=
\begin_inset Quotes erd
\end_inset

 option.
 GEM will then automatically install the extension into the GRASS installation
 that is currently running.
 We will assume this to be true for the following usage examples, as it
 saves me some typing work (\SpecialChar \ldots{}
).
 
\end_layout

\begin_layout Standard
The new modules provided by the extension should be available to you immediately
 from within a GRASS session.
 The extension will be registered as 
\begin_inset Quotes eld
\end_inset

RasterTools
\begin_inset Quotes erd
\end_inset

.
 To get a list of newly installed GRASS modules:
\end_layout

\begin_layout LyX-Code
gem64 --query=RasterTools
\end_layout

\begin_layout Standard
This will display all sorts of information about your freshly installed
 extension, including the installed modules (under 
\begin_inset Quotes eld
\end_inset

Commands provided
\begin_inset Quotes erd
\end_inset

).
 If it is too much information to display on your terminal, pipe it through
 
\emph on
more
\emph default
 and press space to see one page after another:
\end_layout

\begin_layout LyX-Code
gem64 --query=RasterTools | more
\end_layout

\begin_layout Standard
Alternatively, you can browse the GRASS HTML offline help which should now
 contain a link to the extension and its modules from its main page 
\emph on
index.html
\emph default
.
 
\end_layout

\begin_layout Standard
Some extensions may provide menu entries for a GRASS GUI.
 Currently, 
\emph on
d.m
\emph default
 and 
\emph on
gis.m
\emph default
 are supported by GEM.
 Both of these GUIs need to be restarted.
 If the extension provides menu entries, you will find them under 
\begin_inset Quotes eld
\end_inset

Xtns
\begin_inset Quotes erd
\end_inset

 in the main menu bar.
\end_layout

\begin_layout Standard
If you want to know details about an extension before you install it, you
 can also query the extension package itself:
\end_layout

\begin_layout LyX-Code
gem64 --query=RasterTools.tar.gz
\end_layout

\begin_layout Standard
Actions 
\begin_inset Quotes eld
\end_inset

--details=
\begin_inset Quotes erd
\end_inset

 and 
\begin_inset Quotes eld
\end_inset

--license=
\begin_inset Quotes erd
\end_inset

 will give additional information if needed.
 To list all installed extensions (shows name, version and type of installation,
 i.e.
 binaries or compiled from source) in the current GRASS installation, just
 query without any extension name: 
\end_layout

\begin_layout LyX-Code
gem64 -q
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: Awful detail: you must use the short action name 
\begin_inset Quotes eld
\end_inset

-q
\begin_inset Quotes erd
\end_inset

 in this case, not 
\begin_inset Quotes eld
\end_inset

--query=
\begin_inset Quotes erd
\end_inset

 and it has to be at the end of the GEM command line!
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You can also un-install an extension to remove it from the system-wide GRASS
 installation (take name from list produced by above command).
 Again, you need write-access to the GRASS installation dir.
\end_layout

\begin_layout LyX-Code
gem64 --uninstall=AdvancedViewshedAnalysis 
\end_layout

\begin_layout Standard
This should clean your system of all installed modules, HTML pages and GUI
 menu entires.
 Quit and restart the GIS-Manager (
\emph on
d.m
\emph default
) to see the effects of these actions.
 If something goes wrong or you overwrite GIS Manager's menu config file
 (
\emph on
$(PATH_TO_GRASS)/\SpecialChar \-
etc/\SpecialChar \-
dm/\SpecialChar \-
menu.tcl
\emph default
), or you have installed a new version of GRASS (e.g.
 from CVS) and are now missing GUI menu entries and HTML pages for your
 extensions:
\end_layout

\begin_layout LyX-Code
gem64 --restore 
\end_layout

\begin_layout Standard
\SpecialChar \ldots{}
 will try to put everything back in order.
 The program will also create a backup copy 
\emph on
menu.tcl.gem.bak
\emph default
 before it alters 
\emph on
menu.tcl
\emph default
.
 The "--restore" action is also useful if you update or re-install GIS-Manager
 or the GRASS HTML-Documentation in which case both menu entries and HTML
 references have to be restored for all extensions installed.
 
\end_layout

\begin_layout Subsection
Installation of Pre-compiled Binary Extension Files
\begin_inset LatexCommand \label{sub:Installation-of-Pre-compiled}

\end_inset


\end_layout

\begin_layout Standard
Some extensions may provide pre-compiled binary files for one or more operating
 systems.
 A user wishing to install an extension that provides binaries for his OS
 does not need to have C development tools installed.
 This may frequently be the case for users of Mac OS X and Cygwin (but see
 OS specific issues in section 
\begin_inset LatexCommand \ref{sec:OS-Specific-Issues}

\end_inset

).
\end_layout

\begin_layout Standard
It is recommended for all users of GRASS and GEM to install C development
 tools and install extensions from sources (the regular way as described
 in section 
\begin_inset LatexCommand \ref{sub:Basic-Usage}

\end_inset

).
 This will compile the source code into custom binaries that are optimally
 tailored to your system.
 However, there may be circumstances that make using pre-compiled binaries
 appear more convenient or even unavoidable.
\end_layout

\begin_layout Standard
You can check whether an extension provides such pre-compiled binary files
 for your OS by querying the extension package:
\end_layout

\begin_layout LyX-Code
gem64 --query=RasterTools.tar.gz
\end_layout

\begin_layout Standard
If any binaries are provided, they will be listed under "Binary installation
 files".
 You should be able to see whether they are suitable for your system from
 the names.
 E.g.
 
\begin_inset Quotes eld
\end_inset

cygwin
\begin_inset Quotes erd
\end_inset

 would provide binaries for Cygwin users (see section 
\begin_inset LatexCommand \ref{sub:Developers'-Guidelines}

\end_inset

 for conventional names of binaries for different OS).
\end_layout

\begin_layout Standard
Use the option "--binary=" in conjunction with the "--install=" action to
 install the binaries you deem right:
\end_layout

\begin_layout LyX-Code
gem64 --binary=cygwin --install=RasterTools.tar.gz
\end_layout

\begin_layout Standard
This process should finish quicker than regular installation from source
 code as it will skip source code configuration and compilation.
\end_layout

\begin_layout Standard
If you have chosen a wrong set of binaries, new commandes will simply fail
 to start when you try to use them.
\end_layout

\begin_layout Subsection
Additional Options
\end_layout

\begin_layout Standard
Option 
\begin_inset Quotes eld
\end_inset

-f
\begin_inset Quotes erd
\end_inset

 (
\begin_inset Quotes eld
\end_inset

--force
\begin_inset Quotes erd
\end_inset

) can be used to force GEM to re-install an existing extension, over-writing
 anything that was installed previously.
 This is not a recommended thing to do! There is currently no clean updating
 mechanism for GEM, so you are advised to first de-install the existing
 extension (which might involve de-installing all dependent extensions first),
 then install freshly.
\end_layout

\begin_layout Standard
You can also download and install, query etc.
 an extension packages directly from an internet source (http or ftp), provided
 that 
\emph on
wget
\emph default
 is installed (
\begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/wget/wget.html}

\end_inset

):
\end_layout

\begin_layout LyX-Code
gem64 --install=http://www.uni-kiel.de/ufg/dateienDucke/RasterTools.tar.gz
\end_layout

\begin_layout Subsection
Module Versions and Dependencies
\end_layout

\begin_layout Standard
Information about all installed extensions is stored in the file 
\emph on
etc/extensions.db
\emph default
 in your system-wide GRASS installation directory.
 This file contains the names, versions and 
\emph on
dependencies
\emph default
 of all installed extensions.
 Some extensions may need another extension or a particular GRASS version
 to be installed before it can function properly.
 If an extension's dependencies are not met, GEM will abort the installation
 and you need to first install all required software.
\end_layout

\begin_layout Standard
Querying an extension package will let you see the dependencies it has before
 you attempt to install (under 
\begin_inset Quotes eld
\end_inset

Dependencies
\begin_inset Quotes erd
\end_inset

):
\end_layout

\begin_layout LyX-Code
gem64 --query=RasterTools.tar.gz
\end_layout

\begin_layout Standard
Compare this with the output of
\end_layout

\begin_layout LyX-Code
gem64 -q
\end_layout

\begin_layout Standard
...
 and you will know if you need to install something else first.
\end_layout

\begin_layout Standard
You can force installation of extensions with unmatched dependencies by
 using the "--force" option.
 This is not a recommended thing to do! 
\end_layout

\begin_layout Standard
GEM also guards against de-installation of extensions that are still needed
 by other extensions still present on the system.
 You need to un-install all dependent extension in reverse order of installation
 first.
\end_layout

\begin_layout Standard
There is currently no clean updating mechanism for GEM, so you are advised
 to first un-install an existing extension (which might involve de-installing
 all dependent extensions first) before you install a newer version.
\end_layout

\begin_layout Standard
Do not edit 
\emph on
extensions.db
\emph default
 manually, unless you now 
\emph on
exactly
\emph default
 what you are doing!
\end_layout

\begin_layout Section
Developing Extensions for Use with GEM
\begin_inset LatexCommand \label{sec:Developing-Extensions-for}

\end_inset


\end_layout

\begin_layout Standard
Converting existing GRASS add-on modules to a GEM extension package is easy.
 Extensions may provide C program code and headers for modules and libraries,
 shell scripts and tcl code.
 Basically anything that you find a directory for in the skeleton package.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: if your extension needs to install 
\begin_inset Quotes eld
\end_inset

unusual
\begin_inset Quotes erd
\end_inset

 things (additional fonts, tcl widgets, ...) you may need to adapt the top-level
 Makefile in your extension package.
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
GEM Developers' Support
\begin_inset LatexCommand \label{sub:GEM-Developers'-Support}

\end_inset


\end_layout

\begin_layout Standard
The skeleton package (see section 
\begin_inset LatexCommand \ref{sub:The-Skeleton-Package}

\end_inset

) is an almost complete GRASS extension.
 Use this as a template for starting new extensions or migrating existing
 source code from the GRASS source tree.
 All you need to do is copy your source files, scripts etc.
 into the appropriate places in the 
\emph on
src
\emph default
 directory (you will find that everything mirrors the way GRASS sources
 are organized) and fill necessary information into the toplevel ASCII files.
\end_layout

\begin_layout Standard
GEM can configure, compile and install extensions from a plain directory.
 Just provide the name of the directory for all actions.
 This allows you to conveniently keep all your sources and documentations
 in a small, portable directory outside the GRASS source tree and maintain
 everything in there.
\end_layout

\begin_layout Standard
You can test whether an extension compiles and installs on your system by
 using the 
\begin_inset Quotes eld
\end_inset

--test=
\begin_inset Quotes erd
\end_inset

 action.
 This will perform all steps except for actually copying the files to their
 destinations.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: the 
\begin_inset Quotes eld
\end_inset

--test=
\begin_inset Quotes erd
\end_inset

 action simulates the entire installation process, including checks for
 dependencies and already installed extensions.
 This means that testing may result in an error message after successful
 compilation.
 If this annoys, you, use the 
\begin_inset Quotes eld
\end_inset

--force
\begin_inset Quotes erd
\end_inset

 option.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\begin_inset Quotes eld
\end_inset

--clean=
\begin_inset Quotes erd
\end_inset

 action merely exists for the convenience of the developer: it performs
 a make clean in the extensions 
\emph on
src
\emph default
 directory.
\end_layout

\begin_layout Standard
Two more options exist to make life easier for developers: 
\begin_inset Quotes eld
\end_inset

--skip-config
\begin_inset Quotes erd
\end_inset

 to skip source code configuration for speeding up the testing.
 and 
\begin_inset Quotes eld
\end_inset

--options=
\begin_inset Quotes erd
\end_inset

 (sorry about the awful name).
 Everything you specify here will be passed through to the C compiler upon
 compilation of your extension.
\end_layout

\begin_layout Standard
GEM also allows you to use any commands in place of the standard GNU 
\emph on
configure
\emph default
 and 
\emph on
make
\emph default
 tools.
 Specifiy the programs you want to use with the 
\begin_inset Quotes eld
\end_inset

--config-cmd=
\begin_inset Quotes erd
\end_inset

 and 
\begin_inset Quotes eld
\end_inset

make-cmd=
\begin_inset Quotes erd
\end_inset

 options.
\end_layout

\begin_layout Subsection
The Skeleton Package
\begin_inset LatexCommand \label{sub:The-Skeleton-Package}

\end_inset


\end_layout

\begin_layout Standard
The skeleton package is an almost complete GRASS extension.
 Use this as a template for starting new extensions or migrating existing
 source code from the GRASS source tree.
 All you need to do is copy your source files, scripts etc.
 into the appropriate places in the 
\emph on
src
\emph default
 directory (you will find that everything mirrors the way GRASS sources
 are organized) and fill necessary information into the toplevel ASCII files
 (see following sections).
\end_layout

\begin_layout Standard
You will find the skeleton package files in the subdirectory 
\emph on
$GISBASE/etc/gem/skeleton
\emph default
 (replace 
\emph on
$GISBASE
\emph default
 with the path to your GRASS 6.1 install, e.g.
 
\emph on
/usr/local/grass-6.1.cvs
\emph default
).
\end_layout

\begin_layout Standard
Look into the skeleton extension directory and open the ASCII files with
 a texteditor of your choice.
 You will find lots of comments that help you make sense of their contents.
 You can put comments starting with "#" at the beginning of a line or at
 the end in any file.
 These will be filtered out upon parsing of the file by GEM.
\end_layout

\begin_layout Standard
The skeleton contains a copy of the GPL as the default license.
 Creators of new extensions need to be aware of this! Either insert the
 name of your extension at the end of that license or provide your own custom
 licensing information.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: please always provide licensing information!
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Arranging the Source Code
\begin_inset LatexCommand \label{sub:Arranging-the-Source}

\end_inset


\end_layout

\begin_layout Standard
You will find that your makefiles for individual moduls and libs can stay
 largely the way they are.
 One thing that may need to be adjusted is the 
\family typewriter
MODULE_TOPDIR = ..

\family default
 statement that points to the location of the global GRASS makefile 
\emph on
include
\emph default
 directory.
 Also be aware that references to other include files libraries etc.
 that you reference in a makefile may have to be adjusted depending on how
 you decide to structure the source for your extension.
\end_layout

\begin_layout Standard
Take a look at the example module in 
\emph on
src/raster/r.example
\emph default
.
\end_layout

\begin_layout Subsection
Documenting Extension Files
\end_layout

\begin_layout Standard
It is extremely important to provide sufficient documentation about your
 extension's intended use, functionality, dependencies and shortcomings!
\end_layout

\begin_layout Standard
A number of ASCII files in the toplevel extension directory store all this
 information about an extension.
 They must be edited appropriately.
 GEM's 
\begin_inset Quotes eld
\end_inset

--query=
\begin_inset Quotes erd
\end_inset

, 
\begin_inset Quotes eld
\end_inset

--license=
\begin_inset Quotes erd
\end_inset

 and 
\begin_inset Quotes eld
\end_inset

--details=
\begin_inset Quotes erd
\end_inset

 actions will dump their contents to the screen.
 These are:
\end_layout

\begin_layout Standard

\emph on
authors
\emph default
, 
\emph on
bugs
\emph default
, 
\emph on
commands
\emph default
, 
\emph on
depends
\emph default
, 
\emph on
description
\emph default
, 
\emph on
entries-gisman
\emph default
, 
\emph on
entries-gisman2
\emph default
, 
\emph on
headers
\emph default
, 
\emph on
id
\emph default
, 
\emph on
info
\emph default
, 
\emph on
libs
\emph default
, 
\emph on
license
\emph default
 and 
\emph on
name
\emph default
 and 
\emph on
version
\emph default
.
\end_layout

\begin_layout Standard
Files 
\emph on
authors
\emph default
, 
\emph on
bugs
\emph default
, 
\emph on
commands
\emph default
, 
\emph on
description
\emph default
, 
\emph on
headers
\emph default
, 
\emph on
id
\emph default
, 
\emph on
info
\emph default
, 
\emph on
libs
\emph default
: These files are merely for the user's information.
 Their contents will be dumped by the 
\begin_inset Quotes eld
\end_inset

--query=
\begin_inset Quotes erd
\end_inset

 action.
 Much of this information will also go into the system-wide GRASS HTML help.
 Each extension registers its own section in 
\emph on
$GISBASE/docs/html/index.html
\emph default
 which links to an individual index page for that extension.
 This allows the user convenient access to inidividual modules' help pages
 as well as the contents of files 
\emph on
description
\emph default
 and 
\emph on
info
\emph default
.
\end_layout

\begin_layout Standard
Because of this, some description files can contain HTML tags.
 These will be ignored when the user queries the extension on a console
 but will be interpreted when the same information is accessed from the
 GRASS HTML offline help.
 There are two important exceptions: 
\family typewriter
<p>
\family default
 and 
\family typewriter
<br>
\family default
 will produce paragraph and line breaks for console output, as well.
 
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: all other things inside 
\begin_inset Quotes eld
\end_inset

<
\begin_inset Quotes erd
\end_inset

 and 
\begin_inset Quotes eld
\end_inset

>
\begin_inset Quotes erd
\end_inset

 will be filtered out as HTML tags, even if they are not!
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Take a look at the files in the skeleton package for their individual meanings
 and format.
 Files that will be parsed for HTML tags are: 
\emph on
authors
\emph default
, 
\emph on
bugs
\emph default
, 
\emph on
description
\emph default
 and 
\emph on
info
\emph default
.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: your modules' individual HTML manual pages have to be slightly adapted:
 please prefix 
\family typewriter
<a href=>
\family default
 style references to GRASS modules that are not part of the extension with
 
\family typewriter
../../html/
\family default
.
 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
File 
\emph on
license
\emph default
: this will be display by the 
\begin_inset Quotes eld
\end_inset

--license=
\begin_inset Quotes erd
\end_inset

 action.
\end_layout

\begin_layout Standard
File 
\emph on
info
\emph default
: this will be displayed by the 
\begin_inset Quotes eld
\end_inset

--details=
\begin_inset Quotes erd
\end_inset

 action and also integrated in the HTML index page for the extension.
\end_layout

\begin_layout Standard
Files 
\emph on
depends
\emph default
, 
\emph on
name
\emph default
 and 
\emph on
version
\emph default
: see section 
\begin_inset LatexCommand \ref{sub:Version-Information}

\end_inset

.
\end_layout

\begin_layout Standard
Files 
\emph on
entries-gisman
\emph default
 and 
\emph on
entries-gisman2
\emph default
: see section 
\begin_inset LatexCommand \ref{sub:Providing-GUI-Hooks}

\end_inset

.
\end_layout

\begin_layout Subsection
Version Information
\begin_inset LatexCommand \label{sub:Version-Information}

\end_inset


\end_layout

\begin_layout Standard
The file 
\emph on
name
\emph default
 is a very crucial one! It contains the name under which GEM will register
 your extension.
 Please see 
\begin_inset LatexCommand \ref{sub:Developers'-Guidelines}

\end_inset

 about naming conventions!
\end_layout

\begin_layout Standard
The file 
\emph on
version
\emph default
 stores the current version number of your extension.
 Make sure to keep this up-to-date prior to new releases.
\end_layout

\begin_layout Standard
If your extension depends on other extensions or a specific GRASS version,
 you can state this in the 
\emph on
depends
\emph default
 file.
 See the example in the skeleton extension for details.
 GEM will respect this information when a user tries to install or uninstall
 any extension.
\end_layout

\begin_layout Subsection
Un-install and Post-install Actions
\end_layout

\begin_layout Standard
Two files remain that have not been discussed yet:
\emph on
 uninstall
\emph default
 and 
\emph on
post
\emph default
.
\end_layout

\begin_layout Standard
The 
\emph on
uninstall
\emph default
 file is a shell script that contains all commands necessary to clean up
 the GRASS installation after the user invoked GEM with the 
\begin_inset Quotes eld
\end_inset

--uninstall=
\begin_inset Quotes erd
\end_inset

 action to un-install an extension.
 It takes care of deleting module binaries, HTML manpages, C include files
 and libraries provided by that extension from 
\emph on
$GISBASE
\emph default
.
 In the most simple case, all you need to do is provide the list of your
 extension's user commands in 
\family typewriter
EXT_MODULES=
\begin_inset Quotes erd
\end_inset


\begin_inset Quotes erd
\end_inset


\family default
.
 For more complex extensions, you may have to provide additional files to
 delete or even customize 
\emph on
uninstall
\emph default
.
 Take a look at the file in the skeleton extension to see what it does in
 detail.
\end_layout

\begin_layout Standard
GEM will copy your extension's uninstall script to 
\emph on
$GISBASE/etc/uninstall.ExtensionName
\emph default
 and it will be run from there by the 
\begin_inset Quotes eld
\end_inset

--uninstall=
\begin_inset Quotes erd
\end_inset

 action.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: be very careful when adapting the 
\emph on
uninstall
\emph default
 script! It is run with superuser privileges (or those of whatever user
 owns the GRASS installation directory).
 If you provide wrong paths there is no limit to the damage it can do to
 the user's system! Try to keep your changes to a minimum if you have to
 make any.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
post
\emph default
 script can be used to customise many actions in case your extension needs
 anything not provided by the regular make system or GEM description files.
 GEM exports a number of environment variables depending on what options
 and actions the user chose to run it with.
 The 
\emph on
post
\emph default
 script is automatically run after many actions and can be used to carry
 out custom tasks depending on the type of action.
 Take a look at the file provided by the skeletion extension to see what
 can be done.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: be very careful when adapting the 
\emph on
post
\emph default
 script! It is run with superuser privileges (or those of whatever user
 owns the GRASS installation directory).
 If you add flawed commands there is no limit to the damage it can do to
 the user's system!
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Providing GUI Hooks
\begin_inset LatexCommand \label{sub:Providing-GUI-Hooks}

\end_inset


\end_layout

\begin_layout Standard
GEM currently supports the installation of menu items for GIS Manager: the
 old version (
\emph on
d.m
\emph default
) and the new on (
\emph on
gis.m
\emph default
) are both support.
 Support for 
\emph on
d.m
\emph default
 menus is quite limited.
 You can only create one submenu and any number of menu items and separators
 inside of it.
 Menus for 
\emph on
gis.m
\emph default
 can contain any tk menu code.
 You can have as many levels of menu hierarchy as you like.
 See the examples in the skeleton extension to learn how they are organized.
\end_layout

\begin_layout Standard
The file responsible for creating 
\emph on
d.m
\emph default
 menu entries is 
\emph on
entries-gisman
\emph default
.
 For 
\emph on
gis.m
\emph default
 it is 
\emph on
entries-gisman2
\emph default
.
 For 
\emph on
d.m
\emph default
 menus, 
\emph on
entries-gisman
\emph default
 is directly merged into 
\emph on
$GISBASE/etc/dm/menu.tcl
\emph default
.
 GEM will also place a copy of the original 
\emph on
entries-gisman
\emph default
 file into 
\emph on
$GISBASE/etc/dm/gem-entries
\emph default
.
 This is used by the 
\begin_inset Quotes eld
\end_inset

--restore
\begin_inset Quotes erd
\end_inset

 action to restore 
\emph on
d.m
\emph default
 menus in case the user updates the GRASS installation and menu.tcl gets
 overwritten.
 For the purpose of un-installation, markers are stored as comments at the
 end of 
\emph on
menu.tcl
\emph default
.
 This allows the 
\begin_inset Quotes eld
\end_inset

--uninstall=
\begin_inset Quotes erd
\end_inset

 action to find an extensions menu entries and delete them.
 The file 
\emph on
menu.tcl
\emph default
 will be backed up as 
\emph on
menu.tcl.gem.bak
\emph default
 so a user can restore it if anything should wrong.
\end_layout

\begin_layout Standard
Things work much simpler for 
\emph on
gis.m
\emph default
.
 In this case, 
\emph on
$GISBASE/etc/gm/gmmenu.tcl
\emph default
 dynamically re-builds the 
\begin_inset Quotes eld
\end_inset

Xtns
\begin_inset Quotes erd
\end_inset

 menu upon start-up.
 If 
\emph on
entries-gisman2
\emph default
 exists in an extension package, GEM will make sure to create an directory
 
\emph on
Xtns
\emph default
 in 
\emph on
$GISBASE/etc/gm/
\emph default
 and copies 
\emph on
entries-gisman2
\emph default
 into it, renaming it to the extension's name.
 From these files, 
\emph on
gis.m
\emph default
 will automatically build the 
\begin_inset Quotes eld
\end_inset

Xtns
\begin_inset Quotes erd
\end_inset

 menu via some parsing code in 
\emph on
gmmenu.tcl
\emph default
.
\end_layout

\begin_layout Standard
Your submenu will be sorted in under the "Xtns" menu in alphabetical position
 according to either the name of the top level menu item (
\emph on
d.m
\emph default
) or the extension name (
\emph on
gis.m
\emph default
) it is smart to keep both the same (see guidelines in section 
\begin_inset LatexCommand \ref{sub:Developers'-Guidelines}

\end_inset

).
 
\end_layout

\begin_layout Standard
Both 
\emph on
d.m
\emph default
 and 
\emph on
gis.m
\emph default
 need to be restarted to see the effects of installing new menu entries.
\end_layout

\begin_layout Subsection
Customizing the configure script
\end_layout

\begin_layout Standard
If an extension is to be installed from source code, it needs to be configured
 first.
 This is done by the script 
\emph on
configure
\emph default
 in the 
\emph on
src
\emph default
 directory of the extension package.
 The original GRASS configure script checks the system for a number of optional
 dependencies, such as PostgreSQL or Tcl/Tk which are not strictly required
 to run GRASS but may greatly enhance the sytem's functionality.
 Certain GRASS modules may or may not be compiled depending on what optional
 sofware is installed on the system (and correctly detected by the configure
 script).
 In certain situations (such as a missing PostgreSQL installation), the
 GRASS configure script will fail and compilation not start unless the user
 specifies explicitly that e.g.
 PostgreSQL support is not wanted.
\end_layout

\begin_layout Standard
If one or more modules of an extension need a certain external software
 dependency to be satisfied, the extension author needs to modify the configure
 script of that extension accordingly.
\end_layout

\begin_layout Standard
E.g.
 if PostgreSQL is an absolute requirement for all modules and configure
 should fail in case it cannot be found, set the option
\end_layout

\begin_layout LyX-Code
with_postgres=yes
\end_layout

\begin_layout Standard
in the configure script for your extension (options start at ca.
 line 2600).
 Other dependencies might require more complicated modifications to 
\emph on
configure
\emph default
.
\end_layout

\begin_layout Standard
Arbitrary options can be passed to an extensions 
\emph on
configure
\emph default
 script using GEM's 
\begin_inset Quotes eld
\end_inset

--config-opts=
\begin_inset Quotes erd
\end_inset

 option.
\end_layout

\begin_layout Standard
The default configure script, that ships with the skeleton extension has
 all optional dependencies disabled (ca.
 line 2600 and following of the configure script).
 The check for the proj program and libraries (mandatory for GRASS 6.1) has
 been completely removed.
 If your extension code calls proj directly, you may want to add this part
 of the configure script back in.
\end_layout

\begin_layout Subsection
Cross compilation support
\end_layout

\begin_layout Standard
GEM now supports cross compilation for Win32 targets with the MINGW compiler.
 You need the most recent version of GEM for this to work and the configure
 and make files for the extension need to be up-to-date.
 Copy the following files from skeleton/src into your extension's 
\emph on
src
\emph default
 directory to overwrite the old files and update them for cross compilation:
\end_layout

\begin_layout LyX-Code
        Makefile
\end_layout

\begin_layout LyX-Code
        configure.in
\end_layout

\begin_layout LyX-Code
        configure
\end_layout

\begin_layout LyX-Code
        src/include/Make/*
\end_layout

\begin_layout LyX-Code
        lib/init/Makefile
\end_layout

\begin_layout LyX-Code
        lib/init/prompt.sh
\end_layout

\begin_layout LyX-Code
        tools/build_html_index.sh
\end_layout

\begin_layout Standard
Follow the instructions on this page to setup a basic GRASS cross compilation
 environment: 
\begin_inset LatexCommand \url{http://wiki.qgis.org/qgiswiki/BuildingWindowsBinaryOnLinux}

\end_inset

.
 You need at least a cross-compiled version of GRASS (6.2.0 works well) in
 some directory 
\emph on
$WIN
\emph default
 for this to work.
\end_layout

\begin_layout Standard
Create an executable shell script 
\emph on
wingem
\emph default
 to call GEM and configure the extension with the right options (export
 
\emph on
WIN
\emph default
 to the base directory of your cross compilation setup):
\end_layout

\begin_layout LyX-Code
#!/bin/bash
\end_layout

\begin_layout LyX-Code
$GEMBIN=/usr/local/bin/gem64
\end_layout

\begin_layout LyX-Code
export WIN=/home/user/wingrass
\end_layout

\begin_layout LyX-Code
export TARGET=i586-mingw32msvc
\end_layout

\begin_layout LyX-Code
./$GEMBIN "$@" --config-opts="--prefix=$WIN/i586-mingw32msvc --target=$TARGET
 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-gdal 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-jpeg 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-tiff 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-png 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-tcltk 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-postgres 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-mysql 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-sqlite 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-opengl 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-odbc 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-fftw 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-blas 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-lapack 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-motif 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-freetype 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-glw 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-nls 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-readline 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-opendwg 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-curses 
\backslash

\end_layout

\begin_layout LyX-Code
        --without-x" 
\backslash

\end_layout

\begin_layout LyX-Code
        --config-cmd=winconfigure --make-cmd=winmake
\end_layout

\begin_layout Standard
This makes use of GEM's new ability to use custom configure and make commands:
\end_layout

\begin_layout LyX-Code
./wingem64 --install=<extension> --grass=<grass-install-dir>
\end_layout

\begin_layout Standard
Don't forget to configure your extension to re-generate Platform.make and
 Grass.make (i.e.
 don't use the 
\emph on
-s
\emph default
 flag on the first 
\emph on
wingem64
\emph default
 run).
\end_layout

\begin_layout Standard
You will find the cross-compiled binaries in 
\emph on
$WIN/i586-mingw32msvc/<grass-install-dir> 
\emph default
from there, you can e.g.
 copy them to your QGIS windows installation.
\end_layout

\begin_layout Subsection
Providing Binary Distributions
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: due to great heterogenity of installed system libraries, it is probably
 not worth the effort trying to create generic linux binaries.
 Binaries will work better for homogeneous platforms such as Cygwin and
 Lorenzo Moretti's GRASS for Mac OS X.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It is possible to create an extension package that will
\end_layout

\begin_layout Standard
If not done yet, unpack the extension files into a directory:
\end_layout

\begin_layout LyX-Code
tar -xzvf extensionname.tar.gz
\end_layout

\begin_layout Standard
Compile the extension under the OS that you wish to prepare binaries for
 (see OS specific issues in section 
\begin_inset LatexCommand \ref{sec:OS-Specific-Issues}

\end_inset

 about the additional software you may need to do this).
 You do not need to install, compilation will suffice (don't worry if you
 get an error message about the extension being already installed):
\end_layout

\begin_layout LyX-Code
./gem64 --grass=pathToGRASS -t extensionName
\end_layout

\begin_layout Standard
If the compilation was successful, you will find two new folders in the
 
\emph on
src
\emph default
 directory of the extension directory: 
\emph on
bin.architecture-osname
\emph default
 and 
\emph on
dist.architecture-osname
\emph default
.
 E.g.
 for a Windows/Cygwin compilation the 
\begin_inset Quotes eld
\end_inset

dist
\begin_inset Quotes erd
\end_inset

 directory will frequently be
\end_layout

\begin_layout LyX-Code
dist.i686-pc-cygwin
\end_layout

\begin_layout Standard
(or similar).
 
\end_layout

\begin_layout Standard
Create a new directory on the same level as the 
\emph on
src
\emph default
 directory.
 For an appropriate name, follow the guidelines in section 
\begin_inset LatexCommand \ref{sub:Developers'-Guidelines}

\end_inset

.
 In our Cygwin example, this would be 
\emph on
cygwin
\emph default
.
 In this directory:
\end_layout

\begin_layout Enumerate
move the 
\emph on
dist.architecture-osname
\emph default
 directory here
\end_layout

\begin_layout Enumerate
copy 
\emph on
src/Makefile
\emph default
 here
\end_layout

\begin_layout Enumerate
copy 
\emph on
src/include
\emph default
 (with all subdirectories) here
\end_layout

\begin_layout Standard
Make a slight modification to the copy of Makefile: at the top of the file
 following the definitions for install directories (BINDIR=, INST_DIR=).
 Add another line that reads:
\end_layout

\begin_layout LyX-Code
GISBASE = 
\emph on
dist.architecture-osname
\end_layout

\begin_layout Standard
For our example, this might be:
\end_layout

\begin_layout LyX-Code
GISBASE = dist.i686-pc-cygwin
\end_layout

\begin_layout Standard
(or similar).
 This makes sure that the install command will install binaries from the
 right directory.
\end_layout

\begin_layout Standard
Now, since we are preparing a binary distribution for the sake of people
 who do not have any development tools installed, we need to supply them
 with a copy of the GNU make tools, since this is the tool that will take
 care of the actual installation.
 What we need is really just the program 
\emph on
make
\emph default
.
 We will copy it into a folder 
\emph on
bin
\emph default
 under our new directory.
 In our example, then the copy would go into 
\emph on
cygwin/bin
\emph default
.
\end_layout

\begin_layout Standard
The skeleton extension package already has copies of 
\emph on
make
\emph default
 for Cygwin and Mac OS X in place.
 If you need them for another architecture, download sources from 
\begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/make/}

\end_inset

 and compile the appropriate binaries.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: if your extension consists of only platform independent things that
 need not be compiled (shell script, tcl code, ...), you can create a set of
 binaries on any system in the same way as described above and call the
 binary set "scripts" this will allow the user to install those scripts
 without having developer tools installed!
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Preparing an Extension for Release
\end_layout

\begin_layout Standard
1.
 make sure all ASCII files in the top-level extension directory have the
 necessary information (licensing!).
\end_layout

\begin_layout Standard
2.
 Compile binaries that you may wish to provide for those poor people who
 cannot afford C development tools
\end_layout

\begin_layout Standard
3.
 Clean the sources of compiled binaries (this will not affect binaries that
 you wish to provide and copied into their individual directories).
\end_layout

\begin_layout Standard
4.
 If not done yet, delete the example module directory 
\emph on
src/raster/r.example
\emph default
.
 And remove it from the list of subdirs in 
\emph on
src/raster/Makefile
\emph default
.
\end_layout

\begin_layout Standard
5.
 Pack everything into an archive using GNU tar and gzip.
\end_layout

\begin_layout Standard
6.
 Announce your shiny new extension on the appropriate GRASS mailling list!
\end_layout

\begin_layout Standard
SHORTCOMINGS:
\end_layout

\begin_layout Standard
GEM is not very well-suited to install add-ons consisting of just a single
 module.
 This would need an entire extension with the whole shebang for a single
 module! I is assumed, that people who program for a GIS as a rule produce
 more than just one module for a certain purose and that these can well
 be grouped into extensions.
 
\end_layout

\begin_layout Subsection
Developers' Guidelines
\begin_inset LatexCommand \label{sub:Developers'-Guidelines}

\end_inset


\end_layout

\begin_layout Subsubsection
Naming Extensions
\end_layout

\begin_layout Standard
Please do not use anything fancy for your extension's name (as stored in
 the 
\emph on
name
\emph default
 file in the toplevel directory of your extension): no special characters,
 no whitespaces (including simple 
\begin_inset Quotes eld
\end_inset

space
\begin_inset Quotes erd
\end_inset

).
 Use the same restrictions any sane programmer would use for file naming.
 This ensures that GEM can always correctly parse your extension's name.
\end_layout

\begin_layout Subsubsection
Packaging Extensions
\end_layout

\begin_layout Standard
The recommended way to package an extension is to use GNU 
\emph on
tar
\emph default
 and 
\emph on
gzip
\emph default
 utilities as these will normally be available on any OS running GRASS.
 I recommend you use 
\emph on
.tar.gz
\emph default
 as file extension:
\end_layout

\begin_layout LyX-Code
tar -czvf ExtensionName.tar.gz DirectoryWithExtensionFiles
\end_layout

\begin_layout Standard
Make sure that you do not tar up the files from inside the extension directory!
 This will result in a non-functioning package and also gets users annoyed
 because the files will get decompressed directly into whatever directory
 the extension was compiled and it will be hard to clean up the mess.
 Also, do not use an absolute path to the files.
 Rather, build the archive from the directory that contains your extension
 directory, as shown in the example above.
\end_layout

\begin_layout Subsubsection
HTML-Documentation
\end_layout

\begin_layout Standard
Check the GRASS HTML documentation and follow its style! Please provide
 good documentation for your individual modules as well as some brief and
 detailed information about the intended use, functionality and shortcomings
 of your extension (files 
\emph on
description
\emph default
 and 
\emph on
info
\emph default
, respectively).
 HTML man pages for individual modules have to be named 
\emph on
description.html
\emph default
 and copied into the respective module's source code directory.
\end_layout

\begin_layout Standard
Use an HTML manual page of an existing GRASS 6.1 module for a template.
\end_layout

\begin_layout Standard
At the top of your description.html file, right after the 
\family typewriter
<h2>NAME</h2>
\family default
 tag, include a line like this (user lowercase for the 
\family typewriter
<em> </em>
\family default
 tags!):
\end_layout

\begin_layout Standard

\family typewriter
<em><b>r.modulename</b></em> - Description of module in one line.
\end_layout

\begin_layout Standard
This line will be displayed right after the link to your module in the documenta
tion index and will make it easier for the user to find what he needs.
\end_layout

\begin_layout Subsubsection
Binaries
\end_layout

\begin_layout Standard
Suggested folder names for binary distributions:
\end_layout

\begin_layout Standard
Mac OS X: 
\emph on
macosx
\end_layout

\begin_layout Standard
Cygwin: 
\emph on
cygwin
\end_layout

\begin_layout Standard
Linux (glibc 2.2): 
\emph on
linux22
\end_layout

\begin_layout Standard
Linux (glibc 2.3): 
\emph on
linux23
\end_layout

\begin_layout Standard
Shell scripts: 
\emph on
scripts
\end_layout

\begin_layout Subsubsection
Menu Entries
\end_layout

\begin_layout Standard
Name the Toplevel menu item in your menu files (
\emph on
entries-gisman
\emph default
 and 
\emph on
entries-gisman2
\emph default
) the same as the Extension.
 This will make things much clearer for the user!
\end_layout

\begin_layout Section
\start_of_appendix
OS Specific Issues
\begin_inset LatexCommand \label{sec:OS-Specific-Issues}

\end_inset


\end_layout

\begin_layout Subsection
Mac OS X
\begin_inset LatexCommand \label{sub:Mac-OS-X}

\end_inset


\end_layout

\begin_layout Standard
If you want to run GRASS under Mac OS X you can install Lorenzo Moretti's
 binaries.
 They are frequently updated and easy to install.
 GEM has been tested for this version of GRASS and works well with it.
 
\end_layout

\begin_layout Standard
In order to get this working, you need to install some additinal software
 from the Mac OS X install media.
 Just download from 
\begin_inset LatexCommand \htmlurl{http://wwwamb.bologna.enea.it/forgrass/}

\end_inset

 and follow the instructions in the documentation that comes with the program
 files.
\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: if you want to be able to use any extension package, not only those
 that provide binaries for Mac OS X, you need to install the complete GNU
 C development tools from the Mac OS X installation media.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you are using Lorenzo's binaries, the path to GRASS for any GEM operation
 will be:
\end_layout

\begin_layout Standard

\emph on
/Applications/Grass/grass60.app/Contents/Resources/grass-6.0.0
\end_layout

\begin_layout Standard
or
\end_layout

\begin_layout Standard

\emph on
/Applications/Grass/grass61cvs.app/Contents/Resources/grass-6.1.cvs
\end_layout

\begin_layout Standard
if you decided to also install Lorenzo's copy of the CVS version.
\end_layout

\begin_layout Standard
I cannot provide any information about compiling GRASS from sources for
 Mac OS X as I do not have access to such a machine.
\end_layout

\begin_layout Subsection
GRASS under Windows with Cygwin
\begin_inset LatexCommand \label{sub:GRASS-under-Windows}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Boxed
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 1
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Standard
Note: Operation of GEM under Cygwin is only possible in verbose mode (option
 
\begin_inset Quotes eld
\end_inset

-v
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

--verbose
\begin_inset Quotes erd
\end_inset

)! The problem is that Windows cannot redirect output to stderr.
 This interferes with GEM's message hiding.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Although there is now work underway to create a native Win32 version of
 GRASS, for now the only way to get it running is to use the Cygwin emulation
 layer.
 For instructions on how to do this, see 
\begin_inset LatexCommand \htmlurl{http://geni.ath.cx/grass.html}

\end_inset

.
\end_layout

\begin_layout Standard
Some additional hints about setting up Cygwin:
\end_layout

\begin_layout Itemize
Make sure you set the 
\begin_inset Quotes eld
\end_inset

Default Text File Type
\begin_inset Quotes erd
\end_inset

 to 
\begin_inset Quotes eld
\end_inset

Unix
\begin_inset Quotes erd
\end_inset

 during Setup.
\end_layout

\begin_layout Itemize
If you want to be able to use any extension package, not only those that
 provide binaries for Cygwin, jsut install everything in the 
\begin_inset Quotes eld
\end_inset

Devel
\begin_inset Quotes erd
\end_inset

 category and you will have a complete development system.
\end_layout

\begin_layout Itemize
If you want to be able install extension packages directly from the internet
 (http or ftp sources) using GEM, make sure to install wget, located the
 
\begin_inset Quotes eld
\end_inset

Network
\begin_inset Quotes erd
\end_inset

 category.
\end_layout

\begin_layout Itemize
If you want to use an installation in a network environment with NT domain
 authentication, you may need to update 
\emph on
cygwin1.dll
\emph default
 to a newer version.
 Download from 
\begin_inset LatexCommand \htmlurl{http://cygwin.com/snapshots/}

\end_inset

 and replace the old version in your system search path.
\end_layout

\begin_layout Standard
Under Cygwin, there is no support for the Unix 
\emph on
su
\emph default
 command.
 This means that installation of extensions has to be done by someone with
 appropriate access rights to the GRASS installation directory inside the
 Cygwin installation directory (e.g.
 if you installed cygwin to 
\emph on
C:
\backslash
cygwin
\emph default
, this would be something like 
\emph on
C:
\backslash
cygwin
\backslash
usr
\backslash
local
\backslash
grass-someversion
\emph default
).
\end_layout

\begin_layout Subsubsection
CygwinGRASS
\end_layout

\begin_layout Standard
CygwinGRASS (
\begin_inset LatexCommand \htmlurl{https://www.geographie.uni-freiburg.de/~mlechner/CygwinGRASS/}

\end_inset

) is nice because it has all you need to install and use GRASS under Windows
 on one CD.
 Unfortunately, it has not been updated for a while and now contains fairly
 outdated versions of GRASS.
 See the document on the CD for installation instructions.
 
\end_layout

\begin_layout Standard
Some hints regarding the setup:
\end_layout

\begin_layout Itemize
The CygwinGRASS setup has a little flaw in that it assumes the wrong location
 for the local package directory.
 Click on 
\begin_inset Quotes eld
\end_inset

Browse
\begin_inset Quotes erd
\end_inset

 and select the folder repository on the setup medium.
\end_layout

\begin_layout Itemize
If you want to be able to use any extension package, not only those that
 provide binaries for Cygwin, jsut install everything in the 
\begin_inset Quotes eld
\end_inset

Devel
\begin_inset Quotes erd
\end_inset

 category and you will have a complete development system.
\end_layout

\begin_layout Itemize
If you want to be able install extension packages directly from the internet
 (http or ftp sources) using GEM, make sure to install wget, located the
 
\begin_inset Quotes eld
\end_inset

Network
\begin_inset Quotes erd
\end_inset

 category.
\end_layout

\begin_layout Itemize
If you want to use a CygwinGRASS installation in a network environment with
 NT domain authentication, you will need to update 
\emph on
cygwin1.dll
\emph default
 to a newer version.
 Download from 
\begin_inset LatexCommand \htmlurl{http://cygwin.com/snapshots/}

\end_inset

 and replace the old version in your system search path.
\end_layout

\begin_layout Standard
Browsing HTML helpfiles with the default command 
\begin_inset Quotes eld
\end_inset

iexplore
\begin_inset Quotes erd
\end_inset

 seems to fail.
 However, you can install a different browser and change the environment
 variable 
\family typewriter
GRASS_HTML_BROWSER
\family default
 accordingly.
\end_layout

\begin_layout Section
Technical Information
\end_layout

\begin_layout Subsection
File Layout of a GRASS Extension
\end_layout

\begin_layout Standard
Blue items are 
\family typewriter
\color blue
directories
\family default
\color none
, green ones are 
\family typewriter
\color green
files
\family default
\color none
.
\end_layout

\begin_layout Subsubsection
Toplevel
\end_layout

\begin_layout Standard

\family typewriter
\color green
README
\end_layout

\begin_layout Standard

\family typewriter
\color green
authors, bugs, commands, depends, description, entries-gisman, entries-gisman2,
 headers, id, info, libs, license, name, post, uninstall, version
\end_layout

\begin_layout Standard

\family typewriter
\color blue
src [, cygwin, macosx, other-architecture, \SpecialChar \ldots{}
]
\end_layout

\begin_layout Subsubsection
In Directory 
\emph on
src
\end_layout

\begin_layout Standard

\family typewriter
\color green
COPYING
\end_layout

\begin_layout Standard

\family typewriter
\color green
README
\end_layout

\begin_layout Standard

\family typewriter
\color green
REQUIREMENTS.HTML
\end_layout

\begin_layout Standard

\family typewriter
\color green
Makefile, config.guess, config.sub, onfigure, configure.in, install-sh
\end_layout

\begin_layout Standard

\family typewriter
\color blue
db, demolocation, display, general, imagery, include, lib, man, paint, ps,
 raster, raster3d, scripts, sites, tools, vector, visualization
\end_layout

\begin_layout Subsection
Changes to the GRASS Make System Files
\end_layout

\begin_layout Standard
GEM exports three environment variables that point to the directories storing
 GRASS 6 headers and libs and to the install location (e.g.
 
\emph on
/usr/local/grass-6.2.
\emph default
0):
\end_layout

\begin_layout Standard

\family typewriter
GINSTALL_INC
\end_layout

\begin_layout Standard

\family typewriter
GINSTALL_LIB
\end_layout

\begin_layout Standard

\family typewriter
GINSTALL_DST 
\end_layout

\begin_layout Standard
These have been added to the makefiles so that externally compiled modules
 are able to see those GRASS headers and libs they need.
 
\end_layout

\begin_layout Standard
The following is a protocoll of changes between the configure script and
 makefiles in the GEM skeleton extension and the default GRASS files (version
 6.2.0, Dec.
 3rd 2006).
\end_layout

\begin_layout Subsubsection
configure script
\end_layout

\begin_layout Standard
Everything that checks for optional system libraries and could cause configure
 to fail went has been set to default to 
\begin_inset Quotes eld
\end_inset

no
\begin_inset Quotes erd
\end_inset

.
 This means that extensions that have to check for optional system libraries
 may have to set these defaults differently or even add custom checks.
\end_layout

\begin_layout Standard
By default, the GRASS configure script tries to set up GDAL support and
 fails, if the GDAL libs and headers are not present, unless --without-gdal
 was given as a configure option.
 Since not many extensions are expected to make direct use of the GDAL C
 api, the GDAL check has been changed so that GDAL support is not set up
 per default, unless explicitely specified:
\end_layout

\begin_layout LyX-Code
# Check whether --with-gdal or --without-gdal was given.
\end_layout

\begin_layout LyX-Code
if test "${with_gdal+set}" = set; then
\end_layout

\begin_layout LyX-Code
  withval="$with_gdal"
\end_layout

\begin_layout LyX-Code
  :
\end_layout

\begin_layout LyX-Code
else
\end_layout

\begin_layout LyX-Code
  with_gdal=no
\end_layout

\begin_layout LyX-Code
fi
\end_layout

\begin_layout Standard
In summary print-out section at end of script: got rid of: 
\family typewriter
echo " Startup script in directory: ${bindir}"
\family default
.
 And added some custom text that refers to the extension having been configured.
\end_layout

\begin_layout Subsubsection
main Makefile
\end_layout

\begin_layout Standard
L28: 
\family typewriter
INST_DIR
\family default
 is set according to 
\family typewriter
GINSTALL_DST
\family default
 which is exported by GEM.
\end_layout

\begin_layout Standard
L39: SUBDIRS =: deleted the following: doc, gem, gui, misc, 
\end_layout

\begin_layout Standard
L61: FILES =: deleted all files from the list
\end_layout

\begin_layout Standard
L230: install target 
\family typewriter
real-install
\family default
: commented out everything that seems not strictly necessary for a module
 installation and might interfere with the user's GRASS installation.
 Now exits with error code 
\begin_inset Quotes eld
\end_inset

1
\begin_inset Quotes erd
\end_inset

 on write permission problems.
 This can be caught by GEM and dealt with.
 Only creates 
\emph on
error.log
\emph default
 if a module did not compile.
 This is used to check for compilation errors and abort, if necessary.
\end_layout

\begin_layout Standard
L253: commented out stuff for creating GRASS startup script
\end_layout

\begin_layout Standard
L256: comment out everything relating to GEM installation
\end_layout

\begin_layout Subsubsection
include/Make/Grass.make.in
\end_layout

\begin_layout Standard
L39: added \SpecialChar \ldots{}

\end_layout

\begin_layout LyX-Code
ifdef MINGW 
\end_layout

\begin_layout LyX-Code
EXE_SUFFIX = ".exe" 
\end_layout

\begin_layout LyX-Code
endif
\end_layout

\begin_layout Standard
\SpecialChar \ldots{}
 so that Win32 modules will have the .exe suffix by default (cross-compilation).
\end_layout

\begin_layout Standard
L45: added 
\family typewriter
-I$(GINSTALL_INC)
\family default
 to 
\family typewriter
ARCH_INC
\family default
 
\end_layout

\begin_layout Standard
L51: change to: ARCH_LIBDIR = $(GINSTALL_LIB)
\end_layout

\begin_layout Standard
L57: ARCH_LIBPATH = -L$(ARCH_LIBDIR) -L$(GINSTALL_LIB)
\end_layout

\begin_layout Standard
L82: added 
\family typewriter
$(GEM_C_OPTS)
\family default
 to 
\family typewriter
CFLAGS
\family default
 
\end_layout

\begin_layout Standard
L91-94: commented outlinking of fmode.o object, as this currently breaks
 cross-compilation!
\end_layout

\begin_layout Subsubsection
include/Make/Html.make
\begin_inset Note Note
status collapsed

\begin_layout Standard
This file is new since GRASS 6.2.
 It gets included by Rules.make (see comment there).
\end_layout

\begin_layout Standard
For cross-compilation, it currently does nothing! So no HTML pages will
 be included!
\end_layout

\end_inset


\end_layout

\begin_layout Standard
L77-79: the path to the HTML docs is now expanded with 
\emph on
/extensions/<extensionName>.

\emph default
 The name for the extension is read from 
\family typewriter
GEM_EXT_NAME
\family default
 which is exported by GEM.
 A new link to the extension's main HTML index is inserted into the HTML
 page footer.
\end_layout

\begin_layout Standard
L82-90: this makes a slightly different version of the HTML pages to go
 into the extension's HTML folder 
\emph on
docs/\SpecialChar \-
extensions/\SpecialChar \-
$(GEM_EXT_NAME)
\emph default
 (with adjusted relative links).
 
\family typewriter
GEM_EXT_NAME
\family default
 is exported by the GEM installer tool.
\end_layout

\begin_layout Standard
L105: added 
\family typewriter
$(GINSTALL_LIB)
\family default
 to definition of 
\family typewriter
LD_LIBRARY_PATH_VAR
\family default
 .
\end_layout

\begin_layout Subsubsection
include/Make/Shlib.make
\end_layout

\begin_layout Standard
Replace $(GRASS_VERSION_NUMBER) with $(GEM_EXT_VERSION), as this should
 be the version of the extension, not the GRASS base install:
\end_layout

\begin_layout Standard
L6: SHLIB = 
\family typewriter
$(ARCH_LIBDIR)/$(SHLIB_PREFIX)$(SHLIB_NAME).$(GEM_EXT_VERSION)$(SHLIB_SUFFIX)
\family default
 
\end_layout

\begin_layout Standard
L18: 
\family typewriter
$(SHLIB): $(SHLIB_OBJS) 
\end_layout

\begin_layout LyX-Code
$(SHLIB_LD) -o $@ $(LDFLAGS) $^ $(EXTRA_LIBS) && if [ -z "${MINGW}" ] ;
 then ln -f -s $(notdir $@) $(patsubst %.$(GEM_EXT_VERSION)$(SHLIB_SUFFIX),%$(SHL
IB_SUFFIX),$@); fi
\end_layout

\begin_layout Standard

\family typewriter
GEM_EXT_VERSION
\family default
 installs lib with version number as given in 
\emph on
version
\emph default
 file in extension package.
\end_layout

\begin_layout Subsubsection
lib/init/Makefile
\begin_inset Note Note
status open

\begin_layout Standard
added prompt.sh
\end_layout

\end_inset


\end_layout

\begin_layout Standard
L40-61: commented out everything that seems not strictly necessary for a
 module installation and might interfere with the user's GRASS installation.
\end_layout

\begin_layout Subsubsection
tools/build_html_index.sh 
\end_layout

\begin_layout Standard
L15: expand HTML with 
\emph on
/extensions/$GEM_EXT_NAME
\emph default
 (exported by GEM).
 The HTML default text has been altered in many places to reflect its new
 function for describing extensions.
 GEM also exports the following variables to enrich the HTML default text:
\family typewriter
GEM_EXT_VERSION
\family default
 (extension's version number).
\end_layout

\begin_layout Standard
L38-67: Replaced with intro text for GRASS extensions.
\end_layout

\begin_layout Standard
L147: Replaced GRASS with extension header for module index.
\end_layout

\begin_layout Standard
L211: see above.
\end_layout

\begin_layout Standard
L230: see above
\end_layout

\begin_layout Standard
L253: comment out GEM special comment
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Subsection
GEM Synopsis
\end_layout

\begin_layout LyX-Code
Usage: gem64 [OPTION] [ACTION] [FILE|DIR]
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
Possible ACTIONs are:
\end_layout

\begin_layout LyX-Code
  -i, --install=EXT     install a GRASS extension
\end_layout

\begin_layout LyX-Code
  -u, --uninstall=EXT   remove an extension from GRASS
\end_layout

\begin_layout LyX-Code
  -q, --query=EXT       display information about extension/list installed
\end_layout

\begin_layout LyX-Code
  -d, --details=EXT     display additional details about an extension
\end_layout

\begin_layout LyX-Code
  -c, --clean=EXT       clean extension's source code directories
\end_layout

\begin_layout LyX-Code
  -t, --test=EXT        configure and compile extension, but don't install
\end_layout

\begin_layout LyX-Code
  -l, --license=EXT     show copyright information for an extension
\end_layout

\begin_layout LyX-Code
  -r, --restore         recreate HTML links and GIS Manager entries
\end_layout

\begin_layout LyX-Code
  -h, --help            display this help and exit
\end_layout

\begin_layout LyX-Code
  -V, --version         output version information and exit
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
Possible OPTIONs are:
\end_layout

\begin_layout LyX-Code
  -g, --grass=PATH      path to GRASS installation dir
\end_layout

\begin_layout LyX-Code
  -b, --binary=NAME     no compilation: use binary files for system NAME
\end_layout

\begin_layout LyX-Code
  -f, --force           force action, regardless of dependencies
\end_layout

\begin_layout LyX-Code
  -v, --verbose         display detailed status information
\end_layout

\begin_layout LyX-Code
  -s, --skip-config     skip configure script
\end_layout

\begin_layout LyX-Code
  -x, --config-opts=OPTS        pass OPTS to configure script
\end_layout

\begin_layout LyX-Code
  -o, --options=OPTS    options to pass to the C compiler/linker
\end_layout

\begin_layout LyX-Code
  -C, --config-cmd=CMD  Define custom 'configure' command (default=configure)
\end_layout

\begin_layout LyX-Code
  -m, --make-cmd=CMD    Define custom 'make' command (default=make)
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code

\newpage

\end_layout

\begin_layout Subsection
Current Bugs and Shortcomings
\end_layout

\begin_layout Itemize
Operation under Cygwin only works in verbose mode (option -v)!
\end_layout

\begin_layout Itemize
querying installed extensions or trying to uninstall an extension on a system
 that never had an extension installed will simply segfault (missing extensions.d
b is not handled gracefully)
\end_layout

\begin_layout Itemize
Installation from an internet source currently quits with 
\begin_inset Quotes eld
\end_inset

shell-init: error retrieving current directory: getcwd: cannot access parent
 directories: No such file or directory
\begin_inset Quotes erd
\end_inset

 (may leave some temp files around?)
\end_layout

\begin_layout Itemize
Binary installation mode is not exhaustively tested.
\end_layout

\begin_layout Itemize
The installation of menu items for the old 
\emph on
d.m
\emph default
 GUI is very sensitive to the precise syntax of 
\emph on
menu.tcl
\emph default
.
 If the user has altered this file substantially it is likely that registering
 the extension submenu entries will fail.
\end_layout

\begin_layout Itemize
There is no clean way to upgrade an existing extension and respecting dependenci
es 
\emph on
automatically
\emph default
.
 You can use option 
\begin_inset Quotes eld
\end_inset

-f
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

--force
\begin_inset Quotes erd
\end_inset

 to force over-writing of an extension, but it is safer to uninstall first,
 then install the new version.
 
\end_layout

\begin_layout Itemize
GEM can only manage system-wide installations of extension.
 There is no support for location or mapset-wide management.
\end_layout

\begin_layout Itemize
path to GRASS dynamic libraries needs to be present in system-wider linker
 paths.
\end_layout

\end_body
\end_document