1g.extension(1) GRASS GIS User's Manual g.extension(1)
2
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
13 general, installation, extensions, addons, download
14
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 Flags:
23 -l
24 List available extensions in the official GRASS GIS Addons reposi‐
25 tory
26 -c
28 List available extensions in the official GRASS GIS Addons reposi‐
29 tory including module description
30 -g
32 List available extensions in the official GRASS GIS Addons reposi‐
33 tory (shell script style)
34 -a
36 List locally installed extensions
37 -s
39 Install system-wide (may need system administrator rights)
40 -d
42 Download source code and exit
43 -i
45 Do not install new extension, just compile it
46 -f
48 Force removal when uninstalling extension (operation=remove)
49 -t
51 Operate on toolboxes instead of single modules (experimental)
52 -o
54 url refers to a fork of the official extension repository
55 -j
57 Generates JSON file containing the download URLs of the official
58 Addons
59 --help
61 Print usage summary
62 --verbose
64 Verbose module output
65 --quiet
67 Quiet module output
68 --ui
70 Force launching GUI dialog
71 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 operation=string [required]
78 Operation to be performed
79 Options: add, remove
80 Default: add
81 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 prefix=path
91 Prefix where to install extension (ignored when flag -s is given)
92 Default: $GRASS_ADDON_BASE
93 proxy=proxy[,proxy,...]
95 Set the proxy with: "http=<value>,ftp=<value>"
96 branch=branch
98 Specific branch to fetch addon from (only used when fetching from
99 git)
100
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 Two types of extensions are supported:
107 • Python scripts: they are installed without the need of compila‐
109 tion or (usually) the need of special dependencies.
110 • 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 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 To bulk-update all locally installed GRASS GIS extensions, g.exten‐
125 sion.all module is available.
126 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 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 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 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 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 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 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 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 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 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 Non-official sources are supported on all operating systems except for
190 MS-Windows.
191 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
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 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 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 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 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 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 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
257 Toolboxes in the official repository cannot be downloaded.
258 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
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 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
276 g.extension.all
277 GRASS GIS 8 Addons Manual pages
279 GRASS Addons wiki page.
280
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
289 Available at: g.extension source code (history)
290 Accessed: Saturday Jan 21 21:17:01 2023
292 Main index | General index | Topics index | Keywords index | Graphical
294 index | Full index
295 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
297GRASS 8.2.1 g.extension(1)