1g.extension(1)                Grass User's Manual               g.extension(1)
2
3
4

NAME

6       g.extension  - Maintains GRASS Addons extensions in local GRASS instal‐
7       lation.
8       Downloads and installs extensions from GRASS Addons repository or other
9       source  into  the  local GRASS installation or removes installed exten‐
10       sions.
11

KEYWORDS

13       general, installation, extensions, addons, download
14

SYNOPSIS

16       g.extension
17       g.extension --help
18       g.extension  [-lcgasdift]  extension=name  operation=string   [url=url]
19       [prefix=path]     [proxy=proxy[,proxy,...]]     [--help]    [--verbose]
20       [--quiet]  [--ui]
21
22   Flags:
23       -l
24           List available extensions in the official GRASS GIS Addons  reposi‐
25           tory
26
27       -c
28           List  available extensions in the official GRASS GIS Addons reposi‐
29           tory including module description
30
31       -g
32           List available extensions in the official GRASS GIS Addons  reposi‐
33           tory (shell script style)
34
35       -a
36           List locally installed extensions
37
38       -s
39           Install system-wide (may need system administrator rights)
40
41       -d
42           Download source code and exit
43
44       -i
45           Do not install new extension, just compile it
46
47       -f
48           Force removal when uninstalling extension (operation=remove)
49
50       -t
51           Operate on toolboxes instead of single modules (experimental)
52
53       --help
54           Print usage summary
55
56       --verbose
57           Verbose module output
58
59       --quiet
60           Quiet module output
61
62       --ui
63           Force launching GUI dialog
64
65   Parameters:
66       extension=name [required]
67           Name of extension to install or remove
68           Name of toolbox (set of extensions) when -t flag is given
69
70       operation=string [required]
71           Operation to be performed
72           Options: add, remove
73           Default: add
74
75       url=url
76           URL or directory to get the extension from (supported only on Linux
77           and Mac)
78           The official repository is used by default. User can specify a  ZIP
79           file,  directory or a repository on common hosting services. If not
80           identified, Subversion repository is assumed. See  manual  for  all
81           options.
82
83       prefix=path
84           Prefix where to install extension (ignored when flag -s is given)
85           Default: $GRASS_ADDON_BASE
86
87       proxy=proxy[,proxy,...]
88           Set the proxy with: "http=<value>,ftp=<value>"
89

DESCRIPTION

91       g.extension  downloads  and  installs,  removes  or  updates extensions
92       (addons)  from  the  official  GRASS  GIS  Addons  repository  or  from
93       user-specified  source  code  repositories  into  the  local  GRASS GIS
94       installation.
95
96       Two types of extensions are supported:
97
98           ·   Python scripts: they are installed without the need of compila‐
99               tion or (usually) the need of special dependencies.
100
101           ·   Source code (mostly written in C programming language; may also
102               be written in  C++,  Fortran  or  other  languages):  while  on
103               MS-Windows  systems  the requested GRASS GIS extension is down‐
104               loaded pre-compiled from the GRASS GIS site, on Unix based sys‐
105               tems  the installation is preceded by the automated download of
106               the extension’s source code along with  subsequent  compilation
107               and  installation.   This requires a compiler environment to be
108               present on the user’s computer.
109
110   Managing installed extensions
111       Re-running g.extension  on  an  installed  GRASS  GIS  Addon  extension
112       re-installs the requested extension which may include updates.
113
114       To  bulk-update  all  locally  installed GRASS GIS extensions, g.exten‐
115       sion.all module is available.
116
117   Where the extensions are installed
118       GRASS GIS extensions are installed  by  g.extension  into  a  dedicated
119       directory.   The  default  is a directory for application data and set‐
120       tings  inside  the  user’s  home  directory.   On   GNU/Linux   it   is
121       $HOME/.grass7/addons,  on MS-Windows it is $APPDATA\GRASS7\addons.  The
122       name of the directory is stored in the  GRASS_ADDON_BASE  environmental
123       variable.
124
125       The  flag  -s  changes  this  install target directory to the GRASS GIS
126       installation directory (determined by GISBASE  environmental  variable,
127       e.g.   /usr/)   rather  than  the  default  directory  defined  as  per
128       GRASS_ADDON_BASE (see also documentation for  variables).   g.extension
129       checks   if   the   user   has   permission  to  write  to  GISBASE  or
130       GRASS_ADDON_BASE.
131
132       The place where the extensions are installed can be customized  by  the
133       option  prefix.  Ensuring  that  these extensions will be accessible in
134       GRASS GIS is in this case in the responsibility of the user.
135
136   Source code sources and repositories
137   GRASS GIS Addons repository on GitHub
138       By default, g.extension installs extensions from the official GRASS GIS
139       Addons  GitHub  repository. However, different sources can be specified
140       using the url option.
141
142       Individual extensions can also be installed by providing a URL  to  the
143       source  code  on  GitHub or OSGeo Trac. The latter, however, works only
144       for certain directories where the download of ZIP files was enabled  by
145       project administrators of the trac server.
146
147   Local source code directory
148       Optionally,  new  extension  can  be  also installed from a source code
149       placed in a local directory on disk. This is advantageous when develop‐
150       ing  a  new module.  To keep the directory clean, the directory content
151       is copied to a temporary directory and the compilation happens there.
152
153   Local source code ZIP file
154       In addition, new extension can be also installed from a ZIP file or  an
155       archive file from the TAR family (e.g., .tar.gz or .bz2).  The file can
156       be on disk (specified with a path), or on web (specified by an URL).
157
158   Online repositories: GitHub, GitLab and Bitbucket
159       For well known general hosting services, namely GitHub, GitLab and Bit‐
160       bucket,  g.extension  supports  the  download  of a repository as a ZIP
161       file.  Here the user only needs to provide a base URL to the repository
162       web  page  (with  or  without  the https:// part).  For GitLab and Bit‐
163       bucket, the latest source code in the default branch is downloaded, for
164       GitHub,  the latest source code in the master branch is downloaded.  Of
165       course, a user can still specify the full URL of a ZIP file and install
166       a  specific  branch  or release in this way (ZIP file mechanism will be
167       applied).
168
169       For the official repository,  g.extension  supports  listing  available
170       extensions  (addons)  and  few  other metadata-related operations which
171       depend on a specific infrastructure.  For other sources  and  reposito‐
172       ries,  this  is  not supported because it is assumed that other sources
173       contain only one extension, typically a module or group of modules.
174
175   Needed directory layout
176       When none of the above sources is identified, g.extension assumes  that
177       the source is in a GitHub repository and uses the svn command line tool
178       to obtain the source code. The expected  structure  of  the  repository
179       should be the same as the one of the official repository.
180
181       Non-official  sources are supported on all operating systems except for
182       MS-Windows.
183
184   Compilation and installation
185       On MS-Windows systems, where compilation tools are typically not  read‐
186       ily  locally  installed, g.extension downloads a precompiled executable
187       from the GRASS GIS project server. On all other operating systems where
188       it is not difficult to install compilation tools, g.extension downloads
189       the source code of the requested  extension  (addon)  and  compiles  it
190       locally.   This  applies  for  both C and Python modules as well as any
191       other extensions. The reason is that more things such  as  manual  page
192       are  compiled,  not  only the source code (which is really necessary to
193       compile just in case of C).
194

EXAMPLES

196   Download and install of an extension
197       Download and install r.stream.distance into current GRASS installation
198       g.extension extension=r.stream.distance
199       This installs the extension from the official repository.   For  conve‐
200       nience, a shorter syntax can be used:
201       g.extension r.stream.distance
202
203   Download and install of an extension when behind a proxy
204       Example for an open http proxy:
205       # syntax: http://proxyurl:proxyport
206       g.extension extension=r.stream.distance proxy="http=http://proxy.example.com:8080"
207
208       Example for a proxy with proxy authentication:
209       # syntax: http://username:password@proxyurl:proxyport
210       g.extension extension=r.stream.distance proxy="http=http://username:password@proxy.example.com:8080"
211
212   Managing the extensions
213       List  all available extensions in the official GRASS GIS Addons reposi‐
214       tory:
215       g.extension -l
216       List all locally installed extensions:
217       g.extension -a
218       Removal of a locally installed extension:
219       g.extension extension=r.stream.distance operation=remove
220
221   Installing from various online repositories: GitHub, GitLab, Bitbucket
222       Simple URL to GitHub, GitLab, Bitbucket repositories:
223       g.extension r.example url=github.com/johnsmith/r.example
224       Simple URL to OSGeo Trac (downloads a ZIP file, requires download to be
225       enabled in Trac):
226       g.extension r.example url=trac.osgeo.org/.../r.example
227       In  general, when a ZIP file or other archive is provided, the full URL
228       can be used:
229       g.extension r.example url=http://example.com/.../r.example?format=zip
230       Note that because of MS-Windows  operating  system  architecture,  only
231       official repository is supported on this platform.
232
233   Install a specific version from Addons
234       To  install  a specific version from GRASS GIS Addons, specify the full
235       URL pointing to Trac code browser and include Subversion revision  num‐
236       ber.   For   example,   this  installs  the  version  number  57854  of
237       r.local.relief module:
238       g.extension r.local.relief url="https://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.local.relief?rev=57854&format=zip"
239
240   Installing when writing a module locally
241       Having source code of a GRASS module in a directory  on  disk  one  can
242       install it using:
243       g.extension r.example url=/local/directory/r.example/
244

KNOWN ISSUES

246       Toolboxes in the official repository cannot be downloaded.
247
248       On MS-Windows, only the official repository is working because there is
249       no way of compiling  the  modules  (a  Python  replacement  for  Python
250       scripts should be implemented).
251

TROUBLESHOOTING

253       Since  extensions have to be compiled on Unix based systems (Linux, Mac
254       OSX etc.)  unless a Python extension  is  installed,  a  full  compiler
255       environment must be present on the user’s computer.
256
257   ERROR: Please install GRASS development package
258       While  GRASS  GIS  is  available on the user’s computer, the respective
259       development package is lacking. If GRASS was installed from  a  (Linux)
260       repository,  also the grass-dev* package (commonly named "grass-dev" or
261       "grass-devel",  sometimes  along  with  the  version  number)  must  be
262       installed.
263

SEE ALSO

265        g.extension.all
266
267       GRASS GIS 7 Addons Manual pages
268       GRASS Addons wiki page.
269

AUTHORS

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

SOURCE CODE

278       Available at: g.extension source code (history)
279
280       Main  index | General index | Topics index | Keywords index | Graphical
281       index | Full index
282
283       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
284
285
286
287GRASS 7.8.2                                                     g.extension(1)
Impressum