Geografic-Information-System/scripts/g.extension/g.extension.html

<h2>DESCRIPTION</h2>

<!-- TODO: the use of Addon and extension is not coherent -->

<em>g.extension</em> downloads and installs, removes or updates
extensions (addons) from the official
<a href="https://grass.osgeo.org/grass7/manuals/addons/">GRASS GIS Addons repository</a>
or from user-specified source code repositories into the local GRASS GIS
installation.
<p>
Two types of extensions are supported:
<ul>
<li>Python scripts: they are installed without the need of compilation or (usually)
    the need of special dependencies.</li>
<li>Source code (mostly written in C programming language; may also be written
    in C++, Fortran or other languages): while on MS-Windows systems the requested
    GRASS GIS extension is downloaded pre-compiled from the GRASS GIS site, on Unix
    based systems the installation is preceded by the automated download of the
    extension's source code along with subsequent compilation and installation.
    This requires a compiler environment to be present on the user's computer.</li>
</ul>

<h3>Managing installed extensions</h3>

<p>Re-running <em>g.extension</em> on an installed GRASS GIS Addon
extension re-installs the requested extension which may include
updates.
<p>
To bulk-update all locally installed GRASS GIS extensions, 
<em><a href="g.extension.all.html">g.extension.all</a></em> module
is available.


<h3>Where the extensions are installed</h3>

GRASS GIS extensions are installed by <em>g.extension</em> into a dedicated
directory.
The default is a directory for application data and settings inside
the user's home directory. 
On GNU/Linux it is <tt>$HOME/.grass7/addons</tt>,
on MS-Windows it is <tt>$APPDATA\GRASS7\addons</tt>.
The name of the directory is stored in the <tt>GRASS_ADDON_BASE</tt>
environmental variable.

<p>
The flag <b>-s</b> changes this install target directory to the GRASS GIS
installation directory
(determined by <tt>GISBASE</tt> environmental variable, e.g. <tt>/usr/</tt>)
rather than the default directory defined as per  <tt>GRASS_ADDON_BASE</tt> 
(see also documentation for <a href="variables.html">variables</a>).
<em>g.extension</em> checks if the user has permission to write to
<tt>GISBASE</tt> or <tt>GRASS_ADDON_BASE</tt>.

<p>
The place where the extensions are installed can be customized by
the option <b>prefix</b>. Ensuring that these extensions will be accessible
in GRASS GIS is in this case in the responsibility of the user.

<h3>Compilation and installation</h3>

On MS-Windows systems, where compilation tools are typically not readily
locally installed, <em>g.extension</em> downloads a precompiled executable
from the GRASS GIS project server. On all other operating systems
where it is not difficult to install compilation tools,
<em>g.extension</em> downloads the source code of the requested
extension (addon) and compiles it locally.
This applies for both C and Python modules
as well as any other extensions. The reason is that more things such
as manual page are compiled, not only the source code (which is really
necessary to compile just in case of C).


<h2>EXAMPLES</h2>

<h3>Download and install of an extension</h3>

Download and install <em>r.stream.distance</em> into current GRASS installation

<div class="code"><pre>
g.extension extension=r.stream.distance
</pre></div>

This installs the extension from the official repository.
For convenience, a shorter syntax can be used:

<div class="code"><pre>
g.extension r.stream.distance
</pre></div>

<h3>Download and install of an extension when behind a proxy</h3>

Example for an open http proxy:
<div class="code"><pre>
# syntax: http://proxyurl:proxyport
g.extension extension=r.stream.distance proxy="http://proxy.example.com:8080"
</pre></div>

<p>
Example for a proxy with proxy authentication:
<div class="code"><pre>
# syntax: http://username:password@proxyurl:proxyport
g.extension extension=r.stream.distance proxy="http://username:password@proxy.example.com:8080"
</pre></div>

<h3>Managing the extensions</h3>

List all available extensions in the official GRASS GIS Addons repository:

<div class="code"><pre>
g.extension -l
</pre></div>

List all locally installed extensions:

<div class="code"><pre>
g.extension -a
</pre></div>

Removal of a locally installed extension:

<div class="code"><pre>
g.extension extension=r.stream.distance operation=remove
</pre></div>

<h2>TROUBLESHOOTING</h2>

Since extensions have to be compiled on Unix based systems (Linux, Mac OSX etc.)
unless a Python extension is installed, a full compiler environment must be
present on the user's computer.

<h3>ERROR: Please install GRASS development package</h3>

While GRASS GIS is available on the user's computer, the respective development
package is lacking. If GRASS was installed from a (Linux) repository, also the
grass-dev* package (commonly named "grass-dev" or "grass-devel", sometimes along
with the version number) must be installed.

<h2>SEE ALSO</h2>

<em>
<a href="g.extension.all.html">g.extension.all</a>
</em>

<p>
<a href="https://grass.osgeo.org/grass7/manuals/addons/">GRASS GIS 7 Addons Manual pages</a>
<br>
<a href="http://grasswiki.osgeo.org/wiki/GRASS_AddOns">GRASS Addons</a> wiki page.

<h2>AUTHORS</h2>

Markus Neteler (original shell script)<br>
Martin Landa, Czech Technical University in Prague, Czech Republic (Python rewrite)

<p>
<i>Last changed: $Date$</i>