1g.extension(1) Grass 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 [-lcgasdift] extension=name operation=string [url=url]
19 [prefix=path] [proxy=proxy[,proxy,...]] [--help] [--verbose]
20 [--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 --help
54 Print usage summary
55 --verbose
57 Verbose module output
58 --quiet
60 Quiet module output
61 --ui
63 Force launching GUI dialog
64 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 operation=string [required]
71 Operation to be performed
72 Options: add, remove
73 Default: add
74 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 prefix=path
84 Prefix where to install extension (ignored when flag -s is given)
85 Default: $GRASS_ADDON_BASE
86 proxy=proxy[,proxy,...]
88 Set the proxy with: "http=<value>,ftp=<value>"
89
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 Two types of extensions are supported:
97 · Python scripts: they are installed without the need of compila‐
99 tion or (usually) the need of special dependencies.
100 · 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 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 To bulk-update all locally installed GRASS GIS extensions, g.exten‐
115 sion.all module is available.
116 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 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 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 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 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 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 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 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 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 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 Non-official sources are supported on all operating systems except for
182 MS-Windows.
183 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
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 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 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 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 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 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 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
246 Toolboxes in the official repository cannot be downloaded.
247 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
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 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
265 g.extension.all
266 GRASS GIS 7 Addons Manual pages
268 GRASS Addons wiki page.
269
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
278 Available at: g.extension source code (history)
279 Main index | General index | Topics index | Keywords index | Graphical
281 index | Full index
282 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
284GRASS 7.8.2 g.extension(1)