1g.extension(1)              GRASS GIS 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 [-lcgasdiftoj] extension=name  operation=string   [url=url]
19       [prefix=path]    [proxy=proxy[,proxy,...]]   [branch=branch]   [--help]
20       [--verbose]  [--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       -o
54           url refers to a fork of the official extension repository
55
56       -j
57           Generates  JSON  file  containing the download URLs of the official
58           Addons
59
60       --help
61           Print usage summary
62
63       --verbose
64           Verbose module output
65
66       --quiet
67           Quiet module output
68
69       --ui
70           Force launching GUI dialog
71
72   Parameters:
73       extension=name [required]
74           Name of extension to install or remove
75           Name of toolbox (set of extensions) when -t flag is given
76
77       operation=string [required]
78           Operation to be performed
79           Options: add, remove
80           Default: add
81
82       url=url
83           URL or directory to get the extension from (supported only on Linux
84           and Mac)
85           The  official repository is used by default. User can specify a ZIP
86           file, directory or a repository on common hosting services. If  not
87           identified,  Subversion  repository  is assumed. See manual for all
88           options.
89
90       prefix=path
91           Prefix where to install extension (ignored when flag -s is given)
92           Default: $GRASS_ADDON_BASE
93
94       proxy=proxy[,proxy,...]
95           Set the proxy with: "http=<value>,ftp=<value>"
96
97       branch=branch
98           Specific branch to fetch addon from (only used when  fetching  from
99           git)
100

DESCRIPTION

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

EXAMPLES

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

KNOWN ISSUES

257       Toolboxes in the official repository cannot be downloaded.
258
259       On MS-Windows, only the official repository is working because there is
260       no way of compiling  the  modules  (a  Python  replacement  for  Python
261       scripts should be implemented).
262

TROUBLESHOOTING

264       Since  extensions have to be compiled on Unix based systems (Linux, Mac
265       OSX etc.)  unless a Python extension is installed, a full compiler  en‐
266       vironment must be present on the user’s computer.
267
268   ERROR: Please install GRASS development package
269       While GRASS GIS is available on the user’s computer, the respective de‐
270       velopment package is lacking. If GRASS was  installed  from  a  (Linux)
271       repository,  also the grass-dev* package (commonly named "grass-dev" or
272       "grass-devel", sometimes along with the version  number)  must  be  in‐
273       stalled.
274

SEE ALSO

276        g.extension.all
277
278       GRASS GIS 8 Addons Manual pages
279       GRASS Addons wiki page.
280

AUTHORS

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

SOURCE CODE

289       Available at: g.extension source code (history)
290
291       Accessed: Saturday Jan 21 20:41:00 2023
292
293       Main  index | General index | Topics index | Keywords index | Graphical
294       index | Full index
295
296       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
297
298
299
300GRASS 8.2.1                                                     g.extension(1)
Impressum