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 [-lcgasdiftj] 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 -j
54 Generates JSON file containing the download URLs of the official
55 Addons
56 --help
58 Print usage summary
59 --verbose
61 Verbose module output
62 --quiet
64 Quiet module output
65 --ui
67 Force launching GUI dialog
68 Parameters:
70 extension=name [required]
71 Name of extension to install or remove
72 Name of toolbox (set of extensions) when -t flag is given
73 operation=string [required]
75 Operation to be performed
76 Options: add, remove
77 Default: add
78 url=url
80 URL or directory to get the extension from (supported only on Linux
81 and Mac)
82 The official repository is used by default. User can specify a ZIP
83 file, directory or a repository on common hosting services. If not
84 identified, Subversion repository is assumed. See manual for all
85 options.
86 prefix=path
88 Prefix where to install extension (ignored when flag -s is given)
89 Default: $GRASS_ADDON_BASE
90 proxy=proxy[,proxy,...]
92 Set the proxy with: "http=<value>,ftp=<value>"
93 branch=branch
95 Specific branch to fetch addon from (only used when fetching from
96 git)
97 Default: main
98
100 g.extension downloads and installs, removes or updates extensions
101 (addons) from the official GRASS GIS Addons repository or from
102 user-specified source code repositories into the local GRASS GIS
103 installation.
104 Two types of extensions are supported:
106 · Python scripts: they are installed without the need of compila‐
108 tion or (usually) the need of special dependencies.
109 · Source code (mostly written in C programming language; may also
111 be written in C++, Fortran or other languages): while on
112 MS-Windows systems the requested GRASS GIS extension is down‐
113 loaded pre-compiled from the GRASS GIS site, on Unix based sys‐
114 tems the installation is preceded by the automated download of
115 the extension’s source code along with subsequent compilation
116 and installation. This requires a compiler environment to be
117 present on the user’s computer.
118 Managing installed extensions
120 Re-running g.extension on an installed GRASS GIS Addon extension
121 re-installs the requested extension which may include updates.
122 To bulk-update all locally installed GRASS GIS extensions, g.exten‐
124 sion.all module is available.
125 Where the extensions are installed
127 GRASS GIS extensions are installed by g.extension into a dedicated
128 directory. The default is a directory for application data and set‐
129 tings inside the user’s home directory. On GNU/Linux it is
130 $HOME/.grass7/addons, on MS-Windows it is $APPDATA\GRASS7\addons. The
131 name of the directory is stored in the GRASS_ADDON_BASE environmental
132 variable.
133 The flag -s changes this install target directory to the GRASS GIS
135 installation directory (determined by GISBASE environmental variable,
136 e.g. /usr/) rather than the default directory defined as per
137 GRASS_ADDON_BASE (see also documentation for variables). g.extension
138 checks if the user has permission to write to GISBASE or
139 GRASS_ADDON_BASE.
140 The place where the extensions are installed can be customized by the
142 option prefix. Ensuring that these extensions will be accessible in
143 GRASS GIS is in this case in the responsibility of the user.
144 Source code sources and repositories
146 GRASS GIS Addons repository on GitHub
147 By default, g.extension installs extensions from the official GRASS GIS
148 Addons GitHub repository. However, different sources can be specified
149 using the url option.
150 Individual extensions can also be installed by providing a URL to the
152 source code on GitHub or OSGeo Trac. The latter, however, works only
153 for certain directories where the download of ZIP files was enabled by
154 project administrators of the trac server.
155 Local source code directory
157 Optionally, new extension can be also installed from a source code
158 placed in a local directory on disk. This is advantageous when develop‐
159 ing a new module. To keep the directory clean, the directory content
160 is copied to a temporary directory and the compilation happens there.
161 Local source code ZIP file
163 In addition, new extension can be also installed from a ZIP file or an
164 archive file from the TAR family (e.g., .tar.gz or .bz2). The file can
165 be on disk (specified with a path), or on web (specified by an URL).
166 Online repositories: GitHub, GitLab and Bitbucket
168 For well known general hosting services, namely GitHub, GitLab and Bit‐
169 bucket, g.extension supports the download of a repository as a ZIP
170 file. Here the user only needs to provide a base URL to the repository
171 web page (with or without the https:// part). For GitLab and Bit‐
172 bucket, the latest source code in the default branch is downloaded, for
173 GitHub, the latest source code in the master branch is downloaded. Of
174 course, a user can still specify the full URL of a ZIP file and install
175 a specific branch or release in this way (ZIP file mechanism will be
176 applied).
177 For the official repository, g.extension supports listing available
179 extensions (addons) and few other metadata-related operations which
180 depend on a specific infrastructure. For other sources and reposito‐
181 ries, this is not supported because it is assumed that other sources
182 contain only one extension, typically a module or group of modules.
183 Needed directory layout
185 When none of the above sources is identified, g.extension assumes that
186 the source is in a GitHub repository and uses the svn command line tool
187 to obtain the source code. The expected structure of the repository
188 should be the same as the one of the official repository.
189 Non-official sources are supported on all operating systems except for
191 MS-Windows.
192 Compilation and installation
194 On MS-Windows systems, where compilation tools are typically not read‐
195 ily locally installed, g.extension downloads a precompiled executable
196 from the GRASS GIS project server. On all other operating systems where
197 it is not difficult to install compilation tools, g.extension downloads
198 the source code of the requested extension (addon) and compiles it
199 locally. This applies for both C and Python modules as well as any
200 other extensions. The reason is that more things such as manual page
201 are compiled, not only the source code (which is really necessary to
202 compile just in case of C).
203
205 Download and install of an extension
206 Download and install r.stream.distance into current GRASS installation
207 g.extension extension=r.stream.distance
208 This installs the extension from the official repository. For conve‐
209 nience, a shorter syntax can be used:
210 g.extension r.stream.distance
211 Download and install of an extension when behind a proxy
213 Example for an open http proxy:
214 # syntax: http://proxyurl:proxyport
215 g.extension extension=r.stream.distance proxy="http=http://proxy.example.com:8080"
216 Example for a proxy with proxy authentication:
218 # syntax: http://username:password@proxyurl:proxyport
219 g.extension extension=r.stream.distance proxy="http=http://username:password@proxy.example.com:8080"
220 Managing the extensions
222 List all available extensions in the official GRASS GIS Addons reposi‐
223 tory:
224 g.extension -l
225 List all locally installed extensions:
226 g.extension -a
227 Removal of a locally installed extension:
228 g.extension extension=r.stream.distance operation=remove
229 Installing from various online repositories: GitHub, GitLab, Bitbucket
231 Simple URL to GitHub, GitLab, Bitbucket repositories:
232 g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus"
233 Simple URL to GitHub, GitLab, Bitbucket repositories from a specific
234 (e.g. development) branch:
235 g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus" branch=master
236 Simple URL to OSGeo Trac (downloads a ZIP file, requires download to be
237 enabled in Trac):
238 g.extension r.example url=trac.osgeo.org/.../r.example
239 In general, when a ZIP file or other archive is provided, the full URL
240 can be used:
241 g.extension r.example url=http://example.com/.../r.example?format=zip
242 Note that because of MS-Windows operating system architecture, only
243 official repository is supported on this platform.
244 Install a specific version from Addons
246 To install a specific version from GRASS GIS Addons, specify the full
247 URL pointing to Trac code browser and include Subversion revision num‐
248 ber. For example, this installs the version number 57854 of
249 r.local.relief module:
250 g.extension r.local.relief url="https://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.local.relief?rev=57854&format=zip"
251 Installing when writing a module locally
253 Having source code of a GRASS module in a directory on disk one can
254 install it using:
255 g.extension r.example url=/local/directory/r.example/
256
258 Toolboxes in the official repository cannot be downloaded.
259 On MS-Windows, only the official repository is working because there is
261 no way of compiling the modules (a Python replacement for Python
262 scripts should be implemented).
263
265 Since extensions have to be compiled on Unix based systems (Linux, Mac
266 OSX etc.) unless a Python extension is installed, a full compiler
267 environment must be present on the user’s computer.
268 ERROR: Please install GRASS development package
270 While GRASS GIS is available on the user’s computer, the respective
271 development package is lacking. If GRASS was installed from a (Linux)
272 repository, also the grass-dev* package (commonly named "grass-dev" or
273 "grass-devel", sometimes along with the version number) must be
274 installed.
275
277 g.extension.all
278 GRASS GIS 7 Addons Manual pages
280 GRASS Addons wiki page.
281
283 Markus Neteler (original shell script)
284 Martin Landa, Czech Technical University in Prague, Czech Republic
285 (Python rewrite)
286 Vaclav Petras, NCSU OSGeoREL (support for general sources, partial
287 refactoring)
288
290 Available at: g.extension source code (history)
291 Main index | General index | Topics index | Keywords index | Graphical
293 index | Full index
294 © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
296GRASS 7.8.5 g.extension(1)