Provided by: grass-doc_6.4.3-3_all 
NAME
g.extension - Tool to maintain GRASS extensions in local GRASS installation.
Downloads, installs extensions from GRASS Addons SVN repository into local GRASS installation or removes
installed extensions.
KEYWORDS
general, extensions
SYNOPSIS
g.extension
g.extension help
g.extension [-lsu] [extension=name] [operation=name] svnurl=url [prefix=path] [--verbose]
[--quiet]
Flags:
-l
List available modules in the GRASS Addons SVN repository
-s
Install system-wide (may need system administrator rights)
-u
Install system-wide using sudo
--verbose
Verbose module output
--quiet
Quiet module output
Parameters:
extension=name
Name of extension to install/remove
operation=name
Operation to be performed
Options: add,remove
Default: add
svnurl=url
SVN Addons repository URL
Default: http://svn.osgeo.org/grass/grass-addons/grass6
prefix=path
Prefix where to install extension
Default: $GRASS_ADDON_PATH
DESCRIPTION
g.extension downloads community contributed addon modules from the GRASS-addons Subversion repository
(SVN) and installs them on the local system. These include modules providing specialist functionality,
modules in development and beta testing, newly proposed modules, experimental modules, and simple helper
scripts. There are additional code contributions in the SVN repository which are either incomplete or
complex to install and so not available through g.extension. The addons repository acts in part as an
incubation area, so the code there may not be as polished and well reviewed as the core GRASS modules, or
it may not even work at all. All code is license-compatible with GRASS and can be used, shared, and
modified under the same Free-software terms. You are both welcome and encouraged to contribute your own
scripts there, and so make them available via g.extension, if you feel they would be useful to others.
Re-running the script for an installed GRASS addon module re-installs the requested extension. This is a
handy way to apply updates or rebuild compiled modules after installing a new version of GRASS.
The default action is to install the files into the first directory listed in the GRASS_ADDON_PATH
environment variable. If that has not been set it will default to ~/.grass6/addons/ on UNIX or
%APPDATA%\GRASS6\addons on MS Windows. With suitable administrative permissions you can optionally
install directly into the main GRASS program directory ($GISBASE).
NOTES
The wxGUI contains a graphical extension manager separate to this version of g.extension. The wxGUI
Extension Manager can be found in the Settings menu. While they are generally interchangable, this help
page describes the version of g.extension run from the GRASS command line. If one method of installing
the addon fails you might try again with the other.
Help and man pages installed with the module will be available through the g.manual module.
If your GRASS_ADDON_PATH environment variable contains more than one path, the default action is to use
the first directory in the list. Custom user scripts and installed addons can share the same addons
directory.
Note: Bourne shell and Python scripts run within GRASS that use the g.parser module must be in the
system's search PATH, or else g.parser will not be able to find them and complain about a failure to
obtain the module's interface description. As long as the GRASS_ADDON_PATH environment variable is set
before you start GRASS this will be taken care of automatically at startup.
For users building all of GRASS from source code who have also checked out the GRASS-addons Subversion
repository, an alternate approach is to cd into the addon module's source directory, then run:
make MODULE_TOPDIR=/path/to/grass/source
UNIX users can set up an alias in their ~/.bash_aliases file:
alias gmake643='make MODULE_TOPDIR=/path/to/grass643/source'
Users with GRASS installed from a GNU/Linux package can build without the full GRASS source code
installed, but they will need the associated grass-dev and grass-doc packages installed.
Upgrading the GRASS version and users with multiple versions of GRASS installed on the same system
require special care when dealing with compiled addon modules (those written in C and C++ and linking to
the GRASS C libraries). If you try to run a compiled C addon module which was built using a different
version of GRASS, you will get an error that the module can not find the shared GIS libraries of the
other version, or if it can find them it will still check the internal versions and exit with an error if
they do not match. In these cases you can simply re-run g.extension to rebuild the module and solve the
problem.
You can typically share a single GRASS_ADDON_PATH directory for Bourne shell scripts and Python addon
modules written for any version of GRASS 6. Since your Addon modules and scripts will typically be in
your user's home directory and thus persist even when GRASS is upgraded or reinstalled, some notes on
compatibility:
Forward compatibility: Any script written for GRASS 6.0 or newer should work without
changes with any newer version of GRASS 6. Module names, options, and flag behavior will be
respected for the life of the stable release series.
Backwards compatibility: Scripts written for newer versions of GRASS 6.4 may not work with
earlier versions of GRASS 6 if they use commands which were introduced later in the series.
Other than that, they should be fine.
API compatibility: While GRASS 6's core C library API is reasonably stable (at time of
writing it has not changed in 16 months) it is not guaranteed. ABI compatibility is
typically not maintained and compiled C and C++ modules will need to be recompiled after an
upgrade in GRASS version. Changes to the source code should not be needed however, most
changes are simply the addition of new functionality and care has been taken to avoid the
repurposing or removal of old functions or libraries.
The GRASS Python library: It is still in development, and Python 3 is just around the
corner, so you can expect a few changes but starting with GRASS 6.4.3 the core scripting
library API is expected to remain mostly stable. SWIG access to the GRASS C libraries has
now been removed and replaced by the ctypes library.
Compatibility with GRASS 7: Not guaranteed. It is suggested to use a separate directory
for your GRASS 7 addons, or name your custom scripts with the version number in the name.
If you wish to write dual-compatible scripts, the g.version module and GRASS_VERSION
environment variable are available for parsing at run-time.
EXAMPLES
Download and install i.landsat.toar into the current GRASS addons directory:
g.extension r.out.kml
BUGS
This is a relatively new module and obtaining successful behavior on all platforms is rather tricky.
Please report any problems to the GRASS bug tracker. If this automatic build fails, instructions for
compiling both the GRASS source code and GRASS addons by hand can be found in the GRASS wiki.
Note that Bourne shell and Python scripts can simply be downloaded from the online Subversion repository
browser and moved into your GRASS_ADDON_PATH directory by hand. On UNIX you will likely need to set the
executable bit using chmod before the script will run. In this case the associated usage section of the
help page will not be created.
Installing addon Python scripts on MS Windows is still experimental and is not guaranteed to work
properly at run-time due to association of ".py" file extensions with python.exe. It is possible to run
them, but be aware that you will typically need to call them with ".py" as part of the module name.
SEE ALSO
The GRASS Addons module listing in the GRASS Wiki
The wxGUI extension manager (found in the Settings menu)
Details on contributing modules you have written to the GRASS addons repository can be
found in the GRASS Development Wiki
AUTHORS
Markus Neteler
Martin Landa
Hamish Bowman
Last changed: $Date: 2013-07-03 11:25:54 +0200 (Wed, 03 Jul 2013) $
Full index
© 2003-2013 GRASS Development Team
GRASS 6.4.3 g.extension(1grass)