Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
g.extension(1)		    GRASS GIS User's Manual		g.extension(1)

NAME
       g.extension  - Maintains	GRASS Addons extensions	in local GRASS instal-
       lation.
       Downloads and installs extensions from GRASS Addons repository or other
       source  into  the  local	GRASS installation or removes installed	exten-
       sions.

KEYWORDS
       general,	installation, extensions, addons, download

SYNOPSIS
       g.extension
       g.extension --help
       g.extension  [-lcgasdift]  extension=name  operation=string   [url=url]
       [prefix=path]	 [proxy=proxy[,proxy,...]]     [--help]	   [--verbose]
       [--quiet]  [--ui]

   Flags:
       -l
	   List	available extensions in	the official GRASS GIS Addons  reposi-
	   tory

       -c
	   List	 available extensions in the official GRASS GIS	Addons reposi-
	   tory	including module description

       -g
	   List	available extensions in	the official GRASS GIS Addons  reposi-
	   tory	(shell script style)

       -a
	   List	locally	installed extensions

       -s
	   Install system-wide (may need system	administrator rights)

       -d
	   Download source code	and exit

       -i
	   Do not install new extension, just compile it

       -f
	   Force removal when uninstalling extension (operation=remove)

       -t
	   Operate on toolboxes	instead	of single modules (experimental)

       --help
	   Print usage summary

       --verbose
	   Verbose module output

       --quiet
	   Quiet module	output

       --ui
	   Force launching GUI dialog

   Parameters:
       extension=nameA [required]
	   Name	of extension to	install	or remove
	   Name	of toolbox (set	of extensions) when -t flag is given

       operation=stringA [required]
	   Operation to	be performed
	   Options: add, remove
	   Default: add

       url=url
	   URL or directory to get the extension from (supported only on Linux
	   and Mac)
	   The official	repository is used by default. User can	specify	a  ZIP
	   file,  directory or a repository on common hosting services.	If not
	   identified, Subversion repository is	assumed. See  manual  for  all
	   options.

       prefix=path
	   Prefix where	to install extension (ignored when flag	-s is given)
	   Default: $GRASS_ADDON_BASE

       proxy=proxy[,proxy,...]
	   Set the proxy with: "http=<value>,ftp=<value>"

DESCRIPTION
       g.extension  downloads and installs, removes or updates extensions (ad-
       dons) from the official GRASS GIS Addons	repository or from user-speci-
       fied source code	repositories into the local GRASS GIS installation.

       Two types of extensions are supported:

	   o   Python scripts: they are	installed without the need of compila-
	       tion or (usually) the need of special dependencies.

	   o   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	 down-
	       loaded pre-compiled from	the GRASS GIS site, on Unix based sys-
	       tems 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.

   Managing installed extensions
       Re-running g.extension on an installed GRASS GIS	Addon extension	re-in-
       stalls the requested extension which may	include	updates.

       To bulk-update all locally installed  GRASS  GIS	 extensions,  g.exten-
       sion.all	module is available.

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

       The  flag -s changes this install target	directory to the GRASS GIS in-
       stallation directory (determined	 by  GISBASE  environmental  variable,
       e.g. /usr/) rather than the default directory defined as	per  GRASS_AD-
       DON_BASE	(see also documentation	for variables).	 g.extension checks if
       the user	has permission to write	to GISBASE or GRASS_ADDON_BASE.

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

   Source code sources and repositories
   GRASS GIS Addons repository on GitHub
       By default, g.extension installs	extensions from	the official GRASS GIS
       Addons GitHub repository. However, different sources can	 be  specified
       using the url option.

       Individual  extensions  can also	be installed by	providing a URL	to the
       source code on GitHub or	OSGeo Trac. The	latter,	 however,  works  only
       for  certain directories	where the download of ZIP files	was enabled by
       project administrators of the trac server.

   Local source	code directory
       Optionally, new extension can be	also  installed	 from  a  source  code
       placed in a local directory on disk. This is advantageous when develop-
       ing a new module.  To keep the directory	clean, the  directory  content
       is copied to a temporary	directory and the compilation happens there.

   Local source	code ZIP file
       In  addition, new extension can be also installed from a	ZIP file or an
       archive file from the TAR family	(e.g., .tar.gz or .bz2).  The file can
       be on disk (specified with a path), or on web (specified	by an URL).

   Online repositories:	GitHub,	GitLab and Bitbucket
       For well	known general hosting services,	namely GitHub, GitLab and Bit-
       bucket, g.extension supports the	download of  a	repository  as	a  ZIP
       file.  Here the user only needs to provide a base URL to	the repository
       web page	(with or without the https://  part).	For  GitLab  and  Bit-
       bucket, the latest source code in the default branch is downloaded, for
       GitHub, the latest source code in the master branch is downloaded.   Of
       course, a user can still	specify	the full URL of	a ZIP file and install
       a specific branch or release in this way	(ZIP file  mechanism  will  be
       applied).

       For the official	repository, g.extension	supports listing available ex-
       tensions	(addons) and few other metadata-related	operations  which  de-
       pend on a specific infrastructure.  For other sources and repositories,
       this is not supported because it	is assumed that	other sources  contain
       only one	extension, typically a module or group of modules.

   Needed directory layout
       When  none of the above sources is identified, g.extension assumes that
       the source is in	a GitHub repository and	uses the svn command line tool
       to  obtain  the	source	code. The expected structure of	the repository
       should be the same as the one of	the official repository.

       Non-official sources are	supported on all operating systems except  for
       MS-Windows.

   Compilation and installation
       On  MS-Windows systems, where compilation tools are typically not read-
       ily locally installed, g.extension downloads a  precompiled  executable
       from the	GRASS GIS project server. On all other operating systems where
       it is not difficult to install compilation tools, g.extension downloads
       the  source code	of the requested extension (addon) and compiles	it lo-
       cally.  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 com-
       piled, not only the source code (which is really	necessary  to  compile
       just in case of C).

EXAMPLES
   Download and	install	of an extension
       Download	and install r.stream.distance into current GRASS installation
       g.extension extension=r.stream.distance
       This  installs  the extension from the official repository.  For	conve-
       nience, a shorter syntax	can be used:
       g.extension r.stream.distance

   Download and	install	of an extension	when behind a proxy
       Example for an open http	proxy:
       # syntax: http://proxyurl:proxyport
       g.extension extension=r.stream.distance proxy="http=http://proxy.example.com:8080"

       Example for a proxy with	proxy authentication:
       # syntax: http://username:password@proxyurl:proxyport
       g.extension extension=r.stream.distance proxy="http=http://username:password@proxy.example.com:8080"

   Managing the	extensions
       List all	available extensions in	the official GRASS GIS Addons  reposi-
       tory:
       g.extension -l
       List all	locally	installed extensions:
       g.extension -a
       Removal of a locally installed extension:
       g.extension extension=r.stream.distance operation=remove

   Installing from various online repositories:	GitHub,	GitLab,	Bitbucket
       Simple URL to GitHub, GitLab, Bitbucket repositories:
       g.extension r.example url=github.com/johnsmith/r.example
       Simple URL to OSGeo Trac	(downloads a ZIP file, requires	download to be
       enabled in Trac):
       g.extension r.example url=trac.osgeo.org/.../r.example
       In general, when	a ZIP file or other archive is provided, the full  URL
       can be used:
       g.extension r.example url=http://example.com/.../r.example?format=zip
       Note that because of MS-Windows operating system	architecture, only of-
       ficial repository is supported on this platform.

   Install a specific version from Addons
       To install a specific version from GRASS	GIS Addons, specify  the  full
       URL  pointing to	Trac code browser and include Subversion revision num-
       ber. For	example, this installs the version number 57854	of r.local.re-
       lief module:
       g.extension r.local.relief url="https://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.local.relief?rev=57854&format=zip"

   Installing when writing a module locally
       Having source code of a GRASS module in a directory on disk one can in-
       stall it	using:
       g.extension r.example url=/local/directory/r.example/

KNOWN ISSUES
       Toolboxes in the	official repository cannot be downloaded.

       On MS-Windows, only the official	repository is working because there is
       no  way	of  compiling  the  modules  (a	 Python	replacement for	Python
       scripts should be implemented).

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

   ERROR: Please install GRASS development package
       While GRASS GIS is available on the user's computer, the	respective de-
       velopment  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 in-
       stalled.

SEE ALSO
	g.extension.all

       GRASS GIS 7 Addons Manual pages
       GRASS Addons wiki page.

AUTHORS
       Markus Neteler (original	shell script)
       Martin Landa, Czech Technical  University  in  Prague,  Czech  Republic
       (Python rewrite)
       Vaclav  Petras,	NCSU  OSGeoREL	(support  for general sources, partial
       refactoring)

SOURCE CODE
       Available at: g.extension source	code (history)

       Main index | General index | Topics index | Keywords index |  Graphical
       index | Full index

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.3 Reference	Manual

GRASS 7.8.3							g.extension(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | EXAMPLES | KNOWN ISSUES | TROUBLESHOOTING | SEE ALSO | AUTHORS | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=g.extension&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help