<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <!--Converted with LaTeX2HTML 2002-2-1 (1.71) original version by: Nikos Drakos, CBLU, University of Leeds * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan * with significant contributions from: Jens Lippmann, Marek Rouchal, Martin Wilck and others --> <HTML> <HEAD> <TITLE>GRASS Extensions Manager (GEM), Version 1.0.3 Manual</TITLE> <META NAME="description" CONTENT="GRASS Extensions Manager (GEM), Version 1.0.3 Manual"> <META NAME="keywords" CONTENT="GEM-Manual"> <META NAME="resource-type" CONTENT="document"> <META NAME="distribution" CONTENT="global"> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1"> <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> <LINK REL="STYLESHEET" HREF="GEM-Manual.css"> </HEAD> <BODY > <!--Navigation Panel--> <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive" SRC="file:/usr/lib/latex2html/icons/nx_grp_g.png"> <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="file:/usr/lib/latex2html/icons/up_g.png"> <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="file:/usr/lib/latex2html/icons/prev_g.png"> <BR> <BR> <BR> <!--End of Navigation Panel--> <P> <P> <P> <H1 ALIGN="CENTER">GRASS Extensions Manager (GEM), Version 1.0.3 <BR> Manual</H1> <DIV> <P ALIGN="CENTER"><STRONG>Benjamin Ducke (benducke@compuserve.de)</STRONG></P> </DIV> <H3>Abstract:</H3> <DIV> 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 <I>extension</I>. 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 <I>extension package</I> 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. <P> This Document provides instructions for using GEM and for writing portable GRASS extensions to be installed with GEM. <P> </DIV> <P> <BR> <H2><A NAME="SECTION00010000000000000000"> Contents</A> </H2> <!--Table of Contents--> <UL> <LI><A NAME="tex2html49" HREF="GEM-Manual.html#SECTION00020000000000000000">1 Why Do I Need GEM?</A> <LI><A NAME="tex2html50" HREF="GEM-Manual.html#SECTION00030000000000000000">2 How Does GEM Work?</A> <LI><A NAME="tex2html51" HREF="GEM-Manual.html#SECTION00040000000000000000">3 Installation and Usage</A> <UL> <LI><A NAME="tex2html52" HREF="GEM-Manual.html#SECTION00041000000000000000">3.1 Program Installation</A> <LI><A NAME="tex2html53" HREF="GEM-Manual.html#SECTION00042000000000000000">3.2 Installation from Source Code</A> <LI><A NAME="tex2html54" HREF="GEM-Manual.html#SECTION00043000000000000000">3.3 Quickstart</A> <LI><A NAME="tex2html55" HREF="GEM-Manual.html#SECTION00044000000000000000">3.4 Basic Usage</A> <LI><A NAME="tex2html56" HREF="GEM-Manual.html#SECTION00045000000000000000">3.5 Installation of Pre-compiled Binary Extension Files</A> <LI><A NAME="tex2html57" HREF="GEM-Manual.html#SECTION00046000000000000000">3.6 Additional Options</A> <LI><A NAME="tex2html58" HREF="GEM-Manual.html#SECTION00047000000000000000">3.7 Module Versions and Dependencies</A> </UL> <BR> <LI><A NAME="tex2html59" HREF="GEM-Manual.html#SECTION00050000000000000000">4 Developing Extensions for Use with GEM</A> <UL> <LI><A NAME="tex2html60" HREF="GEM-Manual.html#SECTION00051000000000000000">4.1 GEM Developers' Support</A> <LI><A NAME="tex2html61" HREF="GEM-Manual.html#SECTION00052000000000000000">4.2 The Skeleton Package</A> <LI><A NAME="tex2html62" HREF="GEM-Manual.html#SECTION00053000000000000000">4.3 Arranging the Source Code</A> <LI><A NAME="tex2html63" HREF="GEM-Manual.html#SECTION00054000000000000000">4.4 Documenting Extension Files</A> <LI><A NAME="tex2html64" HREF="GEM-Manual.html#SECTION00055000000000000000">4.5 Version Information</A> <LI><A NAME="tex2html65" HREF="GEM-Manual.html#SECTION00056000000000000000">4.6 Un-install and Post-install Actions</A> <LI><A NAME="tex2html66" HREF="GEM-Manual.html#SECTION00057000000000000000">4.7 Providing GUI Hooks</A> <LI><A NAME="tex2html67" HREF="GEM-Manual.html#SECTION00058000000000000000">4.8 Customizing the configure script</A> <LI><A NAME="tex2html68" HREF="GEM-Manual.html#SECTION00059000000000000000">4.9 Cross compilation support</A> <LI><A NAME="tex2html69" HREF="GEM-Manual.html#SECTION000510000000000000000">4.10 Providing Binary Distributions</A> <LI><A NAME="tex2html70" HREF="GEM-Manual.html#SECTION000511000000000000000">4.11 Preparing an Extension for Release</A> <LI><A NAME="tex2html71" HREF="GEM-Manual.html#SECTION000512000000000000000">4.12 Developers' Guidelines</A> </UL> <BR> <LI><A NAME="tex2html72" HREF="GEM-Manual.html#SECTION00060000000000000000">A. OS Specific Issues</A> <UL> <LI><A NAME="tex2html73" HREF="GEM-Manual.html#SECTION00061000000000000000">A..1 Mac OS X</A> <LI><A NAME="tex2html74" HREF="GEM-Manual.html#SECTION00062000000000000000">A..2 GRASS under Windows with Cygwin</A> </UL> <BR> <LI><A NAME="tex2html75" HREF="GEM-Manual.html#SECTION00070000000000000000">B. Technical Information</A> <UL> <LI><A NAME="tex2html76" HREF="GEM-Manual.html#SECTION00071000000000000000">B..1 File Layout of a GRASS Extension</A> <LI><A NAME="tex2html77" HREF="GEM-Manual.html#SECTION00072000000000000000">B..2 Changes to the GRASS Make System Files</A> <LI><A NAME="tex2html78" HREF="GEM-Manual.html#SECTION00073000000000000000">B..3 GEM Synopsis</A> <LI><A NAME="tex2html79" HREF="GEM-Manual.html#SECTION00074000000000000000">B..4 Current Bugs and Shortcomings</A> </UL></UL> <!--End of Table of Contents--> <P> <P> <H1><A NAME="SECTION00020000000000000000"> 1 Why Do I Need GEM?</A> </H1> <P> GRASS GIS (www.grass.itc.it) 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: <P> <OL> <LI>Installation of add-on modules that are not part of the main distribution (http://grass.gdf-hannover.de/twiki/bin/view/GRASS/GrassAddOns) is tedious. It requires a full copy of the GRASS source codes. Add-on sources must be copied to the right locations, compilation and installation must then be started as though one was to install the whole system from scratch. </LI> <LI>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. </LI> <LI>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. </LI> <LI>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-arching documentation to bind them together and make them more accessible from a user's perspective. </LI> <LI>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. </LI> </OL> 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). <P> From the GRASS user's perspective GEM can be used to: <P> <UL> <LI>Conveniently download and install add-on GRASS modules (extensions) that are not part of the CVS. </LI> <LI>Avoid having to keep a complete GRASS source tree on the disk for installing new functionality. </LI> <LI>Install add-on modules from provided binaries without the need to have any development tools installed. </LI> <LI>Manage installed extensions: query, update, uninstall them. </LI> </UL> Form the GRASS developer's perspective GEM allows for: <P> <OL> <LI>Development of GRASS modules completely outside the CVS tree. In a dedicated directory that is much easier to maintain and sync. </LI> <LI>Packaging of module source code, documentation and pre-compiled binaries and deployment as a single file (extension package). </LI> <LI>Simple outsourcing of sets of GRASS functionality from the base distribution into extension packages. </LI> </OL> 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. <P> <H1><A NAME="SECTION00030000000000000000"> 2 How Does GEM Work?</A> </H1> <P> 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. <P> 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. <P> Installed extensions will be registered in <I>$(PATH_TO_GRASS)/etc/extensions.db</I>. 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. <P> They are stored in <I>$(PATH_TO_GRASS)/etc/uninstall.<extension_name></I>. <P> 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. <P> Gem modifies $<I>(PATH_TO_GRASS)/etc/d.m/menu.tcl</I> for this. <P> The extension source code is in the <I>src</I> directory, along with all the necessary makefiles. Other directories may hold pre-compiled binaries and should be named appropriately (<I>win32</I>, <I>macosx</I>, ...). <P> Extensions may provide code for C language modules and libraries, scripts and HTML documentation. <P> GEM compiles and install add-on modules using the sources and makefiles contained in the extension. <P> 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). <P> 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 <A HREF="#sec:Developing-Extensions-for">4</A> of this document. <P> <H1><A NAME="SECTION00040000000000000000"> 3 Installation and Usage</A> </H1> <P> 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. <P> <H2><A NAME="SECTION00041000000000000000"></A><A NAME="sub:Program-Installation"></A> <BR> 3.1 Program Installation </H2> <P> You can download GEM source code and binaries for several different platforms from the author's homepage (http://www.uni-kiel.de/ufg/index1.htm). Check the links at the bottom of the page. You will also find several extension packages for installation with GEM. <P> Download the file <I>gem-someversion.tar.gz</I> to a convenient location, unpack it and change into the newly created directory: <P> <DL COMPACT> <DT> <DD>tar -xzvf gem-<I>someversion</I>.tar.gz <P> cd gem-<I>someversion</I> </DD> </DL>In this directory, you will find a folder <I>bin</I> that contains binaries for different platforms. Change into it and list its contents: <P> <DL COMPACT> <DT> <DD>cd bin <P> ls </DD> </DL>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: <P> <DL COMPACT> <DT> <DD>./gem-cygwin.exe </DD> </DL>You should get a text explaining the program's options on your screeen. <P> 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 <TT>gem</TT>: <P> <DL COMPACT> <DT> <DD>cp gem-cygwin.exe /usr/local/bin/gem </DD> </DL>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 automatically have GEM available system-wide (usually <I>/usr/local/bin</I>) and can just start it with: <P> <DL COMPACT> <DT> <DD>gem6 </DD> </DL>Instructions on how to user GEM to install an actual extension are given in section <A HREF="#sub:Basic-Usage">3.4</A>. <P> <H2><A NAME="SECTION00042000000000000000"> 3.2 Installation from Source Code</A> </H2> <P> <!-- MATH $\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: please make sure that you system-wide linker path includes the location of the GRASS dynamic libraries (e.g. \emph{/usr/local/grass-6.1.cvs/libs}). This is usually done by adding an appropriate entry to \emph{/etc/ld.so.conf} and running \emph{ldconfig}. You may have to consult your system's administrator.% }}%$ --> <IMG WIDTH="566" HEIGHT="105" ALIGN="BOTTOM" BORDER="0" SRC="img1.png" ALT="\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: please make sure that... ...ning \emph{ldconfig}. You may have to consult your system's administrator.% }}%"> <P> 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 ``Development tools''). Mac OS X and Cygwin users: see OS specific notes in section <A HREF="#sec:OS-Specific-Issues">A</A>. <P> Download the file <I>gem-someversion.tar.gz</I> to a convenient location, unpack it and change into the newly created directory: <P> <DL COMPACT> <DT> <DD>tar -xzvf gem-<I>someversion</I>.tar.gz <P> cd gem-<I>someversion</I> </DD> </DL>In this directory, start the compilation process: <P> <DL COMPACT> <DT> <DD>make </DD> </DL>Afer a few seconds, the compilation is done and you have an executable file that you can start from the current directory: <P> <DL COMPACT> <DT> <DD>./gem6 </DD> </DL>... or copy the executable to a system-wide directory, such as <I>/usr/local/bin</I>. <P> <H2><A NAME="SECTION00043000000000000000"> 3.3 Quickstart</A> </H2> <P> <!-- MATH $\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: please be aware that GEM can only install modules in a specially prepared package. See section 4 for how to do this.% }}%$ --> <IMG WIDTH="566" HEIGHT="53" ALIGN="BOTTOM" BORDER="0" SRC="img2.png" ALT="\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: please be aware that ... ...modules in a specially prepared package. See section 4 for how to do this.% }}%"> <P> 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: <P> <DL COMPACT> <DT> <DD>gem6 -install=<I>ExtensionName</I>.tar.gz </DD> </DL>You will now have to be patient as the extension is verified, configured and its source code compiled. <P> <!-- MATH $\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% 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 {}``- -configure='' 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.% }}%$ --> <IMG WIDTH="566" HEIGHT="158" ALIGN="BOTTOM" BORDER="0" SRC="img3.png" ALT="\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: if configuration fail... ...use national language support but not try to find the PostgreSQL software.% }}%"> <P> 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 ``Xtns'' 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! <P> <H2><A NAME="SECTION00044000000000000000"></A><A NAME="sub:Basic-Usage"></A> <BR> 3.4 Basic Usage </H2> <P> <!-- MATH $\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: Operation of GEM under Cygwin is only possible in verbose mode (option {}``-v'' or {}``- -verbose'')! Please read section A.2 on Windows specific issues.% }}%$ --> <IMG WIDTH="566" HEIGHT="53" ALIGN="BOTTOM" BORDER="0" SRC="img4.png" ALT="\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: Operation of GEM unde... ...' or {}\lq\lq -verbose'')! Please read section A.2 on Windows specific issues.% }}%"> <P> 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 <I>/usr/local/grass-6.0.0</I> 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 <A HREF="#sub:Mac-OS-X">A.1</A> for how to find the path to your installation). Also, the extension package used in the following examples is called <I>RasterTools.tar.gz</I> and is in ``tar'd gzip'' format. Replace this with the name of the extension you wish to install as needed. <P> I will further assume that you (or your system's administrator) have copied the executable <I>gem6</I> into a directory from where it can be started system-wide (such as <I>/usr/local/bin</I>) without having to prefix the path to the executable (see instructions in <A HREF="#sub:Program-Installation">3.1</A>). <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% 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. \par For unpacking extension packages you need the appropriate software. Depending on the format of the archive, this could be \emph{tar}, \emph{gzip}, \emph{bunzip2} and \emph{unzip}. \par If you want to get extensions from an internet source (http or ftp), you also need \emph{wget}. 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{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="236" ALIGN="BOTTOM" BORDER="0" SRC="img5.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: in order to i... ...to locate a copy for your OS using an internet search engine.% \end{minipage}}%"> <P> 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. ``-i'' is a short option that does exactly the same as ``-install=''. To see all options, short and long, simply call GEM without any options or ``-help'': <P> <DL COMPACT> <DT> <DD>gem6 </DD> </DL>The ``-version'' action shows information about the GEM version you are using. <P> You will notice that GEM knows a special sort of options called ``actions'' this are options that cause GEM to operate in some way on the extension. The regular ``options'' are just used to modify the way GEM works. <P> To install a module into your GRASS installation (in this example <I>/usr/local/grass-6.0.0</I>), simply pass the name of the archive containing the extension or the directory with the unpacked files to the ``-install='' action and supply the path to the GRASS installation for which you wish to install the extension (using the ``-grass='' option): <P> <DL COMPACT> <DT> <DD>gem6 -grass=/usr/local/grass-6.0.0 -install=RasterTools.tar.gz </DD> </DL>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. <P> If any errors occur, use option ``-v'' (``-verbose'') to see what is going on. <P> By default, the ``-install='' 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. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% 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 {}``scripts'' in the extension details (under {}``Binary installation files'') 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 {}``scripts'', skipping configuration and compilation steps and avoiding the need to have C development tools installed. % \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="180" ALIGN="BOTTOM" BORDER="0" SRC="img6.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: an extension ... ...and avoiding the need to have C development tools installed. % \end{minipage}}%"> <P> If you invoke GEM from inside a running GRASS session, you can ommit the ``-grass='' 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 (...). <P> The new modules provided by the extension should be available to you immediately from within a GRASS session. The extension will be registered as ``RasterTools''. To get a list of newly installed GRASS modules: <P> <DL COMPACT> <DT> <DD>gem6 -query=RasterTools </DD> </DL>This will display all sorts of information about your freshly installed extension, including the installed modules (under ``Commands provided''). If it is too much information to display on your terminal, pipe it through <I>more</I> and press space to see one page after another: <P> <DL COMPACT> <DT> <DD>gem6 -query=RasterTools | more </DD> </DL>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 <I>index.html</I>. <P> Some extensions may provide menu entries for a GRASS GUI. Currently, <I>d.m</I> and <I>gis.m</I> are supported by GEM. Both of these GUIs need to be restarted. If the extension provides menu entries, you will find them under ``Xtns'' in the main menu bar. <P> If you want to know details about an extension before you install it, you can also query the extension package itself: <P> <DL COMPACT> <DT> <DD>gem6 -query=RasterTools.tar.gz </DD> </DL>Actions ``-details='' and ``-license='' 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: <P> <DL COMPACT> <DT> <DD>gem6 -q </DD> </DL><!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: Awful detail: you must use the short action name {}``-q'' in this case, not {}``- -query='' and it has to be at the end of the GEM command line!% \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="53" ALIGN="BOTTOM" BORDER="0" SRC="img7.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: Awful detail:... ...query='' and it has to be at the end of the GEM command line!% \end{minipage}}%"> <P> 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. <P> <DL COMPACT> <DT> <DD>gem6 -uninstall=AdvancedViewshedAnalysis </DD> </DL>This should clean your system of all installed modules, HTML pages and GUI menu entires. Quit and restart the GIS-Manager (<I>d.m</I>) to see the effects of these actions. If something goes wrong or you overwrite GIS Manager's menu config file (<I>$(PATH_TO_GRASS)/etc/dm/menu.tcl</I>), 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: <P> <DL COMPACT> <DT> <DD>gem6 -restore </DD> </DL>... will try to put everything back in order. The program will also create a backup copy <I>menu.tcl.gem.bak</I> before it alters <I>menu.tcl</I>. 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. <P> <H2><A NAME="SECTION00045000000000000000"></A><A NAME="sub:Installation-of-Pre-compiled"></A> <BR> 3.5 Installation of Pre-compiled Binary Extension Files </H2> <P> 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 <A HREF="#sec:OS-Specific-Issues">A</A>). <P> 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 <A HREF="#sub:Basic-Usage">3.4</A>). 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. <P> You can check whether an extension provides such pre-compiled binary files for your OS by querying the extension package: <P> <DL COMPACT> <DT> <DD>gem6 -query=RasterTools.tar.gz </DD> </DL>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. ``cygwin'' would provide binaries for Cygwin users (see section <A HREF="#sub:Developers_-Guidelines">4.12</A> for conventional names of binaries for different OS). <P> Use the option "-binary=" in conjunction with the "-install=" action to install the binaries you deem right: <P> <DL COMPACT> <DT> <DD>gem6 -binary=cygwin -install=RasterTools.tar.gz </DD> </DL>This process should finish quicker than regular installation from source code as it will skip source code configuration and compilation. <P> If you have chosen a wrong set of binaries, new commandes will simply fail to start when you try to use them. <P> <H2><A NAME="SECTION00046000000000000000"> 3.6 Additional Options</A> </H2> <P> Option ``-f'' (``-force'') 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. <P> You can also download and install, query etc. an extension packages directly from an internet source (http or ftp), provided that <I>wget</I> is installed (http://www.gnu.org/software/wget/wget.html): <P> <DL COMPACT> <DT> <DD>gem6 -install=http://www.uni-kiel.de/ufg/dateienDucke/RasterTools.tar.gz </DD> </DL> <P> <H2><A NAME="SECTION00047000000000000000"> 3.7 Module Versions and Dependencies</A> </H2> <P> Information about all installed extensions is stored in the file <I>etc/extensions.db</I> in your system-wide GRASS installation directory. This file contains the names, versions and <I>dependencies</I> 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. <P> Querying an extension package will let you see the dependencies it has before you attempt to install (under ``Dependencies''): <P> <DL COMPACT> <DT> <DD>gem6 -query=RasterTools.tar.gz </DD> </DL>Compare this with the output of <P> <DL COMPACT> <DT> <DD>gem6 -q </DD> </DL>... and you will know if you need to install something else first. <P> You can force installation of extensions with unmatched dependencies by using the "-force" option. This is not a recommended thing to do! <P> 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. <P> 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. <P> Do not edit <I>extensions.db</I> manually, unless you now <I>exactly</I> what you are doing! <P> <H1><A NAME="SECTION00050000000000000000"></A><A NAME="sec:Developing-Extensions-for"></A> <BR> 4 Developing Extensions for Use with GEM </H1> <P> 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. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: if your extension needs to install {}``unusual'' things (additional fonts, tcl widgets, ...) you may need to adapt the top-level Makefile in your extension package.% \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="79" ALIGN="BOTTOM" BORDER="0" SRC="img8.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: if your exten... ...ed to adapt the top-level Makefile in your extension package.% \end{minipage}}%"> <P> <H2><A NAME="SECTION00051000000000000000"></A><A NAME="sub:GEM-Developers_-Support"></A> <BR> 4.1 GEM Developers' Support </H2> <P> The skeleton package (see section <A HREF="#sub:The-Skeleton-Package">4.2</A>) 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 <I>src</I> directory (you will find that everything mirrors the way GRASS sources are organized) and fill necessary information into the toplevel ASCII files. <P> 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. <P> You can test whether an extension compiles and installs on your system by using the ``-test='' action. This will perform all steps except for actually copying the files to their destinations. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: the {}``- -test='' 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 {}``- -force'' option.% \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="105" ALIGN="BOTTOM" BORDER="0" SRC="img9.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: the {}\lq\lq -tes... ...mpilation. If this annoys, you, use the {}\lq\lq -force'' option.% \end{minipage}}%"> <P> The ``-clean='' action merely exists for the convenience of the developer: it performs a make clean in the extensions <I>src</I> directory. <P> Two more options exist to make life easier for developers: ``-skip-config'' to skip source code configuration for speeding up the testing. and ``-options='' (sorry about the awful name). Everything you specify here will be passed through to the C compiler upon compilation of your extension. <P> GEM also allows you to use any commands in place of the standard GNU <I>configure</I> and <I>make</I> tools. Specifiy the programs you want to use with the ``-config-cmd='' and ``make-cmd='' options. <P> <H2><A NAME="SECTION00052000000000000000"></A><A NAME="sub:The-Skeleton-Package"></A> <BR> 4.2 The Skeleton Package </H2> <P> 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 <I>src</I> 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). <P> You will find the skeleton package files in the subdirectory <I>$GISBASE/etc/gem/skeleton</I> (replace <I>$GISBASE</I> with the path to your GRASS 6.1 install, e.g. <I>/usr/local/grass-6.1.cvs</I>). <P> 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. <P> 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. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: please always provide licensing information!% \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="26" ALIGN="BOTTOM" BORDER="0" SRC="img10.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: please always provide licensing information!% \end{minipage}}%"> <P> <H2><A NAME="SECTION00053000000000000000"></A><A NAME="sub:Arranging-the-Source"></A> <BR> 4.3 Arranging the Source Code </H2> <P> 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 <TT>MODULE_TOPDIR = ..</TT> statement that points to the location of the global GRASS makefile <I>include</I> 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. <P> Take a look at the example module in <I>src/raster/r.example</I>. <P> <H2><A NAME="SECTION00054000000000000000"> 4.4 Documenting Extension Files</A> </H2> <P> It is extremely important to provide sufficient documentation about your extension's intended use, functionality, dependencies and shortcomings! <P> A number of ASCII files in the toplevel extension directory store all this information about an extension. They must be edited appropriately. GEM's ``-query='', ``-license='' and ``-details='' actions will dump their contents to the screen. These are: <P> <I>authors</I>, <I>bugs</I>, <I>commands</I>, <I>depends</I>, <I>description</I>, <I>entries-gisman</I>, <I>entries-gisman2</I>, <I>headers</I>, <I>id</I>, <I>info</I>, <I>libs</I>, <I>license</I> and <I>name</I> and <I>version</I>. <P> Files <I>authors</I>, <I>bugs</I>, <I>commands</I>, <I>description</I>, <I>headers</I>, <I>id</I>, <I>info</I>, <I>libs</I>: These files are merely for the user's information. Their contents will be dumped by the ``-query='' action. Much of this information will also go into the system-wide GRASS HTML help. Each extension registers its own section in <I>$GISBASE/docs/html/index.html</I> 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 <I>description</I> and <I>info</I>. <P> 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: <TT><p></TT> and <TT><br></TT> will produce paragraph and line breaks for console output, as well. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: all other things inside {}``<'' and {}``>'' will be filtered out as HTML tags, even if they are not!% \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="53" ALIGN="BOTTOM" BORDER="0" SRC="img11.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: all other thi... ...\lq >'' will be filtered out as HTML tags, even if they are not!% \end{minipage}}%"> <P> 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: <I>authors</I>, <I>bugs</I>, <I>description</I> and <I>info</I>. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: your modules' individual HTML manual pages have to be slightly adapted: please prefix \texttt{<a href=>} style references to GRASS modules that are not part of the extension with \texttt{../../html/}. % \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="79" ALIGN="BOTTOM" BORDER="0" SRC="img12.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: your modules'... ...hat are not part of the extension with \texttt{../../html/}. % \end{minipage}}%"> <P> File <I>license</I>: this will be display by the ``-license='' action. <P> File <I>info</I>: this will be displayed by the ``-details='' action and also integrated in the HTML index page for the extension. <P> Files <I>depends</I>, <I>name</I> and <I>version</I>: see section <A HREF="#sub:Version-Information">4.5</A>. <P> Files <I>entries-gisman</I> and <I>entries-gisman2</I>: see section <A HREF="#sub:Providing-GUI-Hooks">4.7</A>. <P> <H2><A NAME="SECTION00055000000000000000"></A><A NAME="sub:Version-Information"></A> <BR> 4.5 Version Information </H2> <P> The file <I>name</I> is a very crucial one! It contains the name under which GEM will register your extension. Please see <A HREF="#sub:Developers_-Guidelines">4.12</A> about naming conventions! <P> The file <I>version</I> stores the current version number of your extension. Make sure to keep this up-to-date prior to new releases. <P> If your extension depends on other extensions or a specific GRASS version, you can state this in the <I>depends</I> 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. <P> <H2><A NAME="SECTION00056000000000000000"> 4.6 Un-install and Post-install Actions</A> </H2> <P> Two files remain that have not been discussed yet: <I>uninstall</I> and <I>post</I>. <P> The <I>uninstall</I> file is a shell script that contains all commands necessary to clean up the GRASS installation after the user invoked GEM with the ``-uninstall='' 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 <I>$GISBASE</I>. In the most simple case, all you need to do is provide the list of your extension's user commands in <TT>EXT_MODULES=''''</TT>. For more complex extensions, you may have to provide additional files to delete or even customize <I>uninstall</I>. Take a look at the file in the skeleton extension to see what it does in detail. <P> GEM will copy your extension's uninstall script to <I>$GISBASE/etc/uninstall.ExtensionName</I> and it will be run from there by the ``-uninstall='' action. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: be very careful when adapting the \emph{uninstall} 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{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="105" ALIGN="BOTTOM" BORDER="0" SRC="img13.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: be very caref... ...ry to keep your changes to a minimum if you have to make any.% \end{minipage}}%"> <P> The <I>post</I> 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 <I>post</I> 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. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: be very careful when adapting the \emph{post} 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{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="105" ALIGN="BOTTOM" BORDER="0" SRC="img14.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: be very caref... ...ere is no limit to the damage it can do to the user's system!% \end{minipage}}%"> <P> <H2><A NAME="SECTION00057000000000000000"></A><A NAME="sub:Providing-GUI-Hooks"></A> <BR> 4.7 Providing GUI Hooks </H2> <P> GEM currently supports the installation of menu items for GIS Manager: the old version (<I>d.m</I>) and the new on (<I>gis.m</I>) are both support. Support for <I>d.m</I> menus is quite limited. You can only create one submenu and any number of menu items and separators inside of it. Menus for <I>gis.m</I> 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. <P> The file responsible for creating <I>d.m</I> menu entries is <I>entries-gisman</I>. For <I>gis.m</I> it is <I>entries-gisman2</I>. For <I>d.m</I> menus, <I>entries-gisman</I> is directly merged into <I>$GISBASE/etc/dm/menu.tcl</I>. GEM will also place a copy of the original <I>entries-gisman</I> file into <I>$GISBASE/etc/dm/gem-entries</I>. This is used by the ``-restore'' action to restore <I>d.m</I> 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 <I>menu.tcl</I>. This allows the ``-uninstall='' action to find an extensions menu entries and delete them. The file <I>menu.tcl</I> will be backed up as <I>menu.tcl.gem.bak</I> so a user can restore it if anything should wrong. <P> Things work much simpler for <I>gis.m</I>. In this case, <I>$GISBASE/etc/gm/gmmenu.tcl</I> dynamically re-builds the ``Xtns'' menu upon start-up. If <I>entries-gisman2</I> exists in an extension package, GEM will make sure to create an directory <I>Xtns</I> in <I>$GISBASE/etc/gm/</I> and copies <I>entries-gisman2</I> into it, renaming it to the extension's name. From these files, <I>gis.m</I> will automatically build the ``Xtns'' menu via some parsing code in <I>gmmenu.tcl</I>. <P> Your submenu will be sorted in under the "Xtns" menu in alphabetical position according to either the name of the top level menu item (<I>d.m</I>) or the extension name (<I>gis.m</I>) it is smart to keep both the same (see guidelines in section <A HREF="#sub:Developers_-Guidelines">4.12</A>). <P> Both <I>d.m</I> and <I>gis.m</I> need to be restarted to see the effects of installing new menu entries. <P> <H2><A NAME="SECTION00058000000000000000"> 4.8 Customizing the configure script</A> </H2> <P> If an extension is to be installed from source code, it needs to be configured first. This is done by the script <I>configure</I> in the <I>src</I> 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. <P> 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. <P> E.g. if PostgreSQL is an absolute requirement for all modules and configure should fail in case it cannot be found, set the option <P> <DL COMPACT> <DT> <DD>with_postgres=yes </DD> </DL>in the configure script for your extension (options start at ca. line 2600). Other dependencies might require more complicated modifications to <I>configure</I>. <P> Arbitrary options can be passed to an extensions <I>configure</I> script using GEM's ``-config-opts='' option. <P> 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. <P> <H2><A NAME="SECTION00059000000000000000"> 4.9 Cross compilation support</A> </H2> <P> 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 <I>src</I> directory to overwrite the old files and update them for cross compilation: <P> <DL COMPACT> <DT> <DD> Makefile <P> configure.in <P> configure <P> src/include/Make/* <P> lib/init/Makefile <P> lib/init/prompt.sh <P> tools/build_html_index.sh </DD> </DL>Follow the instructions on this page to setup a basic GRASS cross compilation environment: http://wiki.qgis.org/qgiswiki/BuildingWindowsBinaryOnLinux. You need at least a cross-compiled version of GRASS (6.2.0 works well) in some directory <I>$WIN</I> for this to work. <P> Create an executable shell script <I>wingem</I> to call GEM and configure the extension with the right options (export <I>WIN</I> to the base directory of your cross compilation setup): <P> <DL COMPACT> <DT> <DD>#!/bin/bash <P> $GEMBIN=/usr/local/bin/gem6 <P> export WIN=/home/user/wingrass <P> export TARGET=i586-mingw32msvc <P> ./$GEMBIN "$@" -config-opts="-prefix=$WIN/i586-mingw32msvc -target=$TARGET \ <P> -without-gdal \ <P> -without-jpeg \ <P> -without-tiff \ <P> -without-png \ <P> -without-tcltk \ <P> -without-postgres \ <P> -without-mysql \ <P> -without-sqlite \ <P> -without-opengl \ <P> -without-odbc \ <P> -without-fftw \ <P> -without-blas \ <P> -without-lapack \ <P> -without-motif \ <P> -without-freetype \ <P> -without-glw \ <P> -without-nls \ <P> -without-readline \ <P> -without-opendwg \ <P> -without-curses \ <P> -without-x" \ <P> -config-cmd=winconfigure -make-cmd=winmake </DD> </DL>This makes use of GEM's new ability to use custom configure and make commands: <P> <DL COMPACT> <DT> <DD>./wingem6 -install=<extension> -grass=<grass-install-dir> </DD> </DL>Don't forget to configure your extension to re-generate Platform.make and Grass.make (i.e. don't use the <I>-s</I> flag on the first <I>wingem6</I> run). <P> You will find the cross-compiled binaries in <I>$WIN/i586-mingw32msvc/<grass-install-dir></I> from there, you can e.g. copy them to your QGIS windows installation. <P> <H2><A NAME="SECTION000510000000000000000"> 4.10 Providing Binary Distributions</A> </H2> <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% 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{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="102" ALIGN="BOTTOM" BORDER="0" SRC="img15.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: due to great ... ...orms such as Cygwin and Lorenzo Moretti's GRASS for Mac OS X.% \end{minipage}}%"> <P> It is possible to create an extension package that will <P> If not done yet, unpack the extension files into a directory: <P> <DL COMPACT> <DT> <DD>tar -xzvf extensionname.tar.gz </DD> </DL>Compile the extension under the OS that you wish to prepare binaries for (see OS specific issues in section <A HREF="#sec:OS-Specific-Issues">A</A> 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): <P> <DL COMPACT> <DT> <DD>./gem6 -grass=pathToGRASS -t extensionName </DD> </DL>If the compilation was successful, you will find two new folders in the <I>src</I> directory of the extension directory: <I>bin.architecture-osname</I> and <I>dist.architecture-osname</I>. E.g. for a Windows/Cygwin compilation the ``dist'' directory will frequently be <P> <DL COMPACT> <DT> <DD>dist.i686-pc-cygwin </DD> </DL>(or similar). <P> Create a new directory on the same level as the <I>src</I> directory. For an appropriate name, follow the guidelines in section <A HREF="#sub:Developers_-Guidelines">4.12</A>. In our Cygwin example, this would be <I>cygwin</I>. In this directory: <P> <OL> <LI>move the <I>dist.architecture-osname</I> directory here </LI> <LI>copy <I>src/Makefile</I> here </LI> <LI>copy <I>src/include</I> (with all subdirectories) here </LI> </OL> 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: <P> <DL COMPACT> <DT> <DD>GISBASE = <I>dist.architecture-osname</I> </DD> </DL>For our example, this might be: <P> <DL COMPACT> <DT> <DD>GISBASE = dist.i686-pc-cygwin </DD> </DL>(or similar). This makes sure that the install command will install binaries from the right directory. <P> 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 <I>make</I>. We will copy it into a folder <I>bin</I> under our new directory. In our example, then the copy would go into <I>cygwin/bin</I>. <P> The skeleton extension package already has copies of <I>make</I> for Cygwin and Mac OS X in place. If you need them for another architecture, download sources from http://www.gnu.org/software/make/ and compile the appropriate binaries. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% 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 \char`\"{}scripts\char`\"{} this will allow the user to install those scripts without having developer tools installed!% \end{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="128" ALIGN="BOTTOM" BORDER="0" SRC="img16.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: if your exten... ...stall those scripts without having developer tools installed!% \end{minipage}}%"> <P> <H2><A NAME="SECTION000511000000000000000"> 4.11 Preparing an Extension for Release</A> </H2> <P> 1. make sure all ASCII files in the top-level extension directory have the necessary information (licensing!). <P> 2. Compile binaries that you may wish to provide for those poor people who cannot afford C development tools <P> 3. Clean the sources of compiled binaries (this will not affect binaries that you wish to provide and copied into their individual directories). <P> 4. If not done yet, delete the example module directory <I>src/raster/r.example</I>. And remove it from the list of subdirs in <I>src/raster/Makefile</I>. <P> 5. Pack everything into an archive using GNU tar and gzip. <P> 6. Announce your shiny new extension on the appropriate GRASS mailling list! <P> SHORTCOMINGS: <P> 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. <P> <H2><A NAME="SECTION000512000000000000000"></A><A NAME="sub:Developers_-Guidelines"></A> <BR> 4.12 Developers' Guidelines </H2> <P> <H3><A NAME="SECTION000512100000000000000"> 4.12.1 Naming Extensions</A> </H3> <P> Please do not use anything fancy for your extension's name (as stored in the <I>name</I> file in the toplevel directory of your extension): no special characters, no whitespaces (including simple ``space''). Use the same restrictions any sane programmer would use for file naming. This ensures that GEM can always correctly parse your extension's name. <P> <H3><A NAME="SECTION000512200000000000000"> 4.12.2 Packaging Extensions</A> </H3> <P> The recommended way to package an extension is to use GNU <I>tar</I> and <I>gzip</I> utilities as these will normally be available on any OS running GRASS. I recommend you use <I>.tar.gz</I> as file extension: <P> <DL COMPACT> <DT> <DD>tar -czvf ExtensionName.tar.gz DirectoryWithExtensionFiles </DD> </DL>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. <P> <H3><A NAME="SECTION000512300000000000000"> 4.12.3 HTML-Documentation</A> </H3> <P> 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 <I>description</I> and <I>info</I>, respectively). HTML man pages for individual modules have to be named <I>description.html</I> and copied into the respective module's source code directory. <P> Use an HTML manual page of an existing GRASS 6.1 module for a template. <P> At the top of your description.html file, right after the <TT><h2>NAME</h2></TT> tag, include a line like this (user lowercase for the <TT><em> </em></TT> tags!): <P> <TT><em><b>r.modulename</b></em> - Description of module in one line.</TT> <P> This line will be displayed right after the link to your module in the documentation index and will make it easier for the user to find what he needs. <P> <H3><A NAME="SECTION000512400000000000000"> 4.12.4 Binaries</A> </H3> <P> Suggested folder names for binary distributions: <P> Mac OS X: <I>macosx</I> <P> Cygwin: <I>cygwin</I> <P> Linux (glibc 2.2): <I>linux22</I> <P> Linux (glibc 2.3): <I>linux23</I> <P> Shell scripts: <I>scripts</I> <P> <H3><A NAME="SECTION000512500000000000000"> 4.12.5 Menu Entries</A> </H3> <P> Name the Toplevel menu item in your menu files (<I>entries-gisman</I> and <I>entries-gisman2</I>) the same as the Extension. This will make things much clearer for the user! <P> <P> <H1><A NAME="SECTION00060000000000000000"></A><A NAME="sec:OS-Specific-Issues"></A> <BR> A. OS Specific Issues </H1> <P> <H2><A NAME="SECTION00061000000000000000"></A><A NAME="sub:Mac-OS-X"></A> <BR> A..1 Mac OS X </H2> <P> 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. <P> In order to get this working, you need to install some additinal software from the Mac OS X install media. Just download from http://wwwamb.bologna.enea.it/forgrass/ and follow the instructions in the documentation that comes with the program files. <P> <!-- MATH $\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% 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{minipage}}%$ --> <IMG WIDTH="566" HEIGHT="79" ALIGN="BOTTOM" BORDER="0" SRC="img17.png" ALT="\framebox{\begin{minipage}[t][1\totalheight]{1\columnwidth}% Note: if you want t... ...GNU C development tools from the Mac OS X installation media.% \end{minipage}}%"> <P> If you are using Lorenzo's binaries, the path to GRASS for any GEM operation will be: <P> <I>/Applications/Grass/grass60.app/Contents/Resources/grass-6.0.0</I> <P> or <P> <I>/Applications/Grass/grass61cvs.app/Contents/Resources/grass-6.1.cvs</I> <P> if you decided to also install Lorenzo's copy of the CVS version. <P> I cannot provide any information about compiling GRASS from sources for Mac OS X as I do not have access to such a machine. <P> <H2><A NAME="SECTION00062000000000000000"></A><A NAME="sub:GRASS-under-Windows"></A> <BR> A..2 GRASS under Windows with Cygwin </H2> <P> <!-- MATH $\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: Operation of GEM under Cygwin is only possible in verbose mode (option {}``-v'' or {}``- -verbose'')! The problem is that Windows cannot redirect output to stderr. This interferes with GEM's message hiding.% }}%$ --> <IMG WIDTH="566" HEIGHT="79" ALIGN="BOTTOM" BORDER="0" SRC="img18.png" ALT="\framebox{\parbox[t][1\totalheight]{1\columnwidth}{% Note: Operation of GEM unde... ...nnot redirect output to stderr. This interferes with GEM's message hiding.% }}%"> <P> 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 http://geni.ath.cx/grass.html. <P> Some additional hints about setting up Cygwin: <P> <UL> <LI>Make sure you set the ``Default Text File Type'' to ``Unix'' during Setup. </LI> <LI>If you want to be able to use any extension package, not only those that provide binaries for Cygwin, jsut install everything in the ``Devel'' category and you will have a complete development system. </LI> <LI>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 ``Network'' category. </LI> <LI>If you want to use an installation in a network environment with NT domain authentication, you may need to update <I>cygwin1.dll</I> to a newer version. Download from http://cygwin.com/snapshots/ and replace the old version in your system search path. </LI> </UL> Under Cygwin, there is no support for the Unix <I>su</I> 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 <I>C:\cygwin</I>, this would be something like <I>C:\cygwin\usr\local\grass-someversion</I>). <P> <H3><A NAME="SECTION00062100000000000000"> A..2.1 CygwinGRASS</A> </H3> <P> CygwinGRASS (https://www.geographie.uni-freiburg.de/ mlechner/CygwinGRASS/) 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. <P> Some hints regarding the setup: <P> <UL> <LI>The CygwinGRASS setup has a little flaw in that it assumes the wrong location for the local package directory. Click on ``Browse'' and select the folder repository on the setup medium. </LI> <LI>If you want to be able to use any extension package, not only those that provide binaries for Cygwin, jsut install everything in the ``Devel'' category and you will have a complete development system. </LI> <LI>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 ``Network'' category. </LI> <LI>If you want to use a CygwinGRASS installation in a network environment with NT domain authentication, you will need to update <I>cygwin1.dll</I> to a newer version. Download from http://cygwin.com/snapshots/ and replace the old version in your system search path. </LI> </UL> Browsing HTML helpfiles with the default command ``iexplore'' seems to fail. However, you can install a different browser and change the environment variable <TT>GRASS_HTML_BROWSER</TT> accordingly. <P> <H1><A NAME="SECTION00070000000000000000"> B. Technical Information</A> </H1> <P> <H2><A NAME="SECTION00071000000000000000"> B..1 File Layout of a GRASS Extension</A> </H2> <P> Blue items are <TT><FONT COLOR="#0000ff">directories</FONT></TT>, green ones are <TT><FONT COLOR="#00ff00">files</FONT></TT>. <P> <H3><A NAME="SECTION00071100000000000000"> B..1.1 Toplevel</A> </H3> <P> <TT><FONT COLOR="#00ff00">README</FONT></TT> <P> <TT><FONT COLOR="#00ff00">authors, bugs, commands, depends, description, entries-gisman, entries-gisman2, headers, id, info, libs, license, name, post, uninstall, version</FONT></TT> <P> <TT><FONT COLOR="#0000ff">src [, cygwin, macosx, other-architecture, ...]</FONT></TT> <P> <H3><A NAME="SECTION00071200000000000000"> B..1.2 In Directory <I>src</I></A> </H3> <P> <TT><FONT COLOR="#00ff00">COPYING</FONT></TT> <P> <TT><FONT COLOR="#00ff00">README</FONT></TT> <P> <TT><FONT COLOR="#00ff00">REQUIREMENTS.HTML</FONT></TT> <P> <TT><FONT COLOR="#00ff00">Makefile, config.guess, config.sub, onfigure, configure.in, install-sh</FONT></TT> <P> <TT><FONT COLOR="#0000ff">db, demolocation, display, general, imagery, include, lib, man, paint, ps, raster, raster3d, scripts, sites, tools, vector, visualization</FONT></TT> <P> <H2><A NAME="SECTION00072000000000000000"> B..2 Changes to the GRASS Make System Files</A> </H2> <P> GEM exports three environment variables that point to the directories storing GRASS 6 headers and libs and to the install location (e.g. <I>/usr/local/grass-6.2.</I>0): <P> <TT>GINSTALL_INC</TT> <P> <TT>GINSTALL_LIB</TT> <P> <TT>GINSTALL_DST </TT> <P> These have been added to the makefiles so that externally compiled modules are able to see those GRASS headers and libs they need. <P> 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). <P> <H3><A NAME="SECTION00072100000000000000"> B..2.1 configure script</A> </H3> <P> Everything that checks for optional system libraries and could cause configure to fail went has been set to default to ``no''. This means that extensions that have to check for optional system libraries may have to set these defaults differently or even add custom checks. <P> 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: <P> <DL COMPACT> <DT> <DD># Check whether -with-gdal or -without-gdal was given. <P> if test "${with_gdal+set}" = set; then <P> withval="$with_gdal" <P> : <P> else <P> with_gdal=no <P> fi </DD> </DL>In summary print-out section at end of script: got rid of: <TT>echo " Startup script in directory: ${bindir}"</TT>. And added some custom text that refers to the extension having been configured. <P> <H3><A NAME="SECTION00072200000000000000"> B..2.2 main Makefile</A> </H3> <P> L28: <TT>INST_DIR</TT> is set according to <TT>GINSTALL_DST</TT> which is exported by GEM. <P> L39: SUBDIRS =: deleted the following: doc, gem, gui, misc, <P> L61: FILES =: deleted all files from the list <P> L230: install target <TT>real-install</TT>: 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 ``1'' on write permission problems. This can be caught by GEM and dealt with. Only creates <I>error.log</I> if a module did not compile. This is used to check for compilation errors and abort, if necessary. <P> L253: commented out stuff for creating GRASS startup script <P> L256: comment out everything relating to GEM installation <P> <H3><A NAME="SECTION00072300000000000000"> B..2.3 include/Make/Grass.make.in</A> </H3> <P> L39: added ... <P> <DL COMPACT> <DT> <DD>ifdef MINGW <P> EXE_SUFFIX = ".exe" <P> endif </DD> </DL>... so that Win32 modules will have the .exe suffix by default (cross-compilation). <P> L45: added <TT>-I$(GINSTALL_INC)</TT> to <TT>ARCH_INC</TT> <P> L51: change to: ARCH_LIBDIR = $(GINSTALL_LIB) <P> L57: ARCH_LIBPATH = -L$(ARCH_LIBDIR) -L$(GINSTALL_LIB) <P> L82: added <TT>$(GEM_C_OPTS)</TT> to <TT>CFLAGS</TT> <P> L91-94: commented outlinking of fmode.o object, as this currently breaks cross-compilation! <P> <H3><A NAME="SECTION00072400000000000000"> B..2.4 include/Make/Html.make</A> </H3> <P> L77-79: the path to the HTML docs is now expanded with <I>/extensions/<extensionName>.</I> The name for the extension is read from <TT>GEM_EXT_NAME</TT> which is exported by GEM. A new link to the extension's main HTML index is inserted into the HTML page footer. <P> L82-90: this makes a slightly different version of the HTML pages to go into the extension's HTML folder <I>docs/extensions/$(GEM_EXT_NAME)</I> (with adjusted relative links). <TT>GEM_EXT_NAME</TT> is exported by the GEM installer tool. <P> L105: added <TT>$(GINSTALL_LIB)</TT> to definition of <TT>LD_LIBRARY_PATH_VAR</TT> . <P> <H3><A NAME="SECTION00072500000000000000"> B..2.5 include/Make/Shlib.make</A> </H3> <P> Replace $(GRASS_VERSION_NUMBER) with $(GEM_EXT_VERSION), as this should be the version of the extension, not the GRASS base install: <P> L6: SHLIB = <TT>$(ARCH_LIBDIR)/$(SHLIB_PREFIX)$(SHLIB_NAME).$(GEM_EXT_VERSION)$(SHLIB_SUFFIX)</TT> <P> L18: <TT>$(SHLIB): $(SHLIB_OBJS) </TT> <P> <DL COMPACT> <DT> <DD>$(SHLIB_LD) -o $@ $(LDFLAGS) $^ $(EXTRA_LIBS) && if [ -z "${MINGW}" ] ; then ln -f -s $(notdir $@) $(patsubst %.$(GEM_EXT_VERSION)$(SHLIB_SUFFIX),%$(SHLIB_SUFFIX),$@); fi </DD> </DL><TT>GEM_EXT_VERSION</TT> installs lib with version number as given in <I>version</I> file in extension package. <P> <H3><A NAME="SECTION00072600000000000000"> B..2.6 lib/init/Makefile</A> </H3> <P> L40-61: commented out everything that seems not strictly necessary for a module installation and might interfere with the user's GRASS installation. <P> <H3><A NAME="SECTION00072700000000000000"> B..2.7 tools/build_html_index.sh </A> </H3> <P> L15: expand HTML with <I>/extensions/$GEM_EXT_NAME</I> (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:<TT>GEM_EXT_VERSION</TT> (extension's version number). <P> L38-67: Replaced with intro text for GRASS extensions. <P> L147: Replaced GRASS with extension header for module index. <P> L211: see above. <P> L230: see above <P> L253: comment out GEM special comment <P> <P> <H2><A NAME="SECTION00073000000000000000"> B..3 GEM Synopsis</A> </H2> <P> <DL COMPACT> <DT> <DD>Usage: gem6 [OPTION] [ACTION] [FILE|DIR] <P> Possible ACTIONs are: <P> -i, -install=EXT install a GRASS extension <P> -u, -uninstall=EXT remove an extension from GRASS <P> -q, -query=EXT display information about extension/list installed <P> -d, -details=EXT display additional details about an extension <P> -c, -clean=EXT clean extension's source code directories <P> -t, -test=EXT configure and compile extension, but don't install <P> -l, -license=EXT show copyright information for an extension <P> -r, -restore recreate HTML links and GIS Manager entries <P> -h, -help display this help and exit <P> -V, -version output version information and exit <P> Possible OPTIONs are: <P> -g, -grass=PATH path to GRASS installation dir <P> -b, -binary=NAME no compilation: use binary files for system NAME <P> -f, -force force action, regardless of dependencies <P> -v, -verbose display detailed status information <P> -s, -skip-config skip configure script <P> -x, -config-opts=OPTS pass OPTS to configure script <P> -o, -options=OPTS options to pass to the C compiler/linker <P> -C, -config-cmd=CMD Define custom 'configure' command (default=configure) <P> -m, -make-cmd=CMD Define custom 'make' command (default=make) <P> </DD> </DL> <P> <H2><A NAME="SECTION00074000000000000000"> B..4 Current Bugs and Shortcomings</A> </H2> <P> <UL> <LI>Operation under Cygwin only works in verbose mode (option -v)! </LI> <LI>querying installed extensions or trying to uninstall an extension on a system that never had an extension installed will simply segfault (missing extensions.db is not handled gracefully) </LI> <LI>Installation from an internet source currently quits with ``shell-init: error retrieving current directory: getcwd: cannot access parent directories: No such file or directory'' (may leave some temp files around?) </LI> <LI>Binary installation mode is not exhaustively tested. </LI> <LI>The installation of menu items for the old <I>d.m</I> GUI is very sensitive to the precise syntax of <I>menu.tcl</I>. If the user has altered this file substantially it is likely that registering the extension submenu entries will fail. </LI> <LI>There is no clean way to upgrade an existing extension and respecting dependencies <I>automatically</I>. You can use option ``-f'' or ``-force'' to force over-writing of an extension, but it is safer to uninstall first, then install the new version. </LI> <LI>GEM can only manage system-wide installations of extension. There is no support for location or mapset-wide management. </LI> <LI>path to GRASS dynamic libraries needs to be present in system-wider linker paths. </LI> </UL> <P> <H1><A NAME="SECTION00080000000000000000"> About this document ...</A> </H1> <STRONG>GRASS Extensions Manager (GEM), Version 1.0.3 <BR> Manual</STRONG><P> This document was generated using the <A HREF="http://www.latex2html.org/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-2-1 (1.71) <P> Copyright © 1993, 1994, 1995, 1996, <A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>, Computer Based Learning Unit, University of Leeds. <BR> Copyright © 1997, 1998, 1999, <A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>, Mathematics Department, Macquarie University, Sydney. <P> The command line arguments were: <BR> <STRONG>latex2html</STRONG> <TT>-split 0 -show_section_numbers GEM-Manual.tex</TT> <P> The translation was initiated by on 2007-03-08<HR> <!--Navigation Panel--> <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive" SRC="file:/usr/lib/latex2html/icons/nx_grp_g.png"> <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="file:/usr/lib/latex2html/icons/up_g.png"> <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="file:/usr/lib/latex2html/icons/prev_g.png"> <BR> <!--End of Navigation Panel--> <ADDRESS> 2007-03-08 </ADDRESS> </BODY> </HTML>