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 [-lcgasdifto] 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 --help
57 Print usage summary
58 --verbose
60 Verbose module output
61 --quiet
63 Quiet module output
64 --ui
66 Force launching GUI dialog
67 Parameters:
69 extension=name [required]
70 Name of extension to install or remove
71 Name of toolbox (set of extensions) when -t flag is given
72 operation=string [required]
74 Operation to be performed
75 Options: add, remove
76 Default: add
77 url=url
79 URL or directory to get the extension from (supported only on Linux
80 and Mac)
81 The official repository is used by default. User can specify a ZIP
82 file, directory or a repository on common hosting services. If not
83 identified, Subversion repository is assumed. See manual for all
84 options.
85 prefix=path
87 Prefix where to install extension (ignored when flag -s is given)
88 Default: $GRASS_ADDON_BASE
89 proxy=proxy[,proxy,...]
91 Set the proxy with: "http=<value>,ftp=<value>"
92 branch=branch
94 Specific branch to fetch addon from (only used when fetching from
95 git)
96
98 g.extension downloads and installs, removes or updates extensions (ad‐
99 dons) from the official GRASS GIS Addons repository or from user-speci‐
100 fied source code repositories into the local GRASS GIS installation.
101 Two types of extensions are supported:
103 • Python scripts: they are installed without the need of compila‐
105 tion or (usually) the need of special dependencies.
106 • Source code (mostly written in C programming language; may also
108 be written in C++, Fortran or other languages): while on
109 MS-Windows systems the requested GRASS GIS extension is down‐
110 loaded pre-compiled from the GRASS GIS site, on Unix based sys‐
111 tems the installation is preceded by the automated download of
112 the extension’s source code along with subsequent compilation
113 and installation. This requires a compiler environment to be
114 present on the user’s computer.
115 Managing installed extensions
117 Re-running g.extension on an installed GRASS GIS Addon extension re-in‐
118 stalls the requested extension which may include updates.
119 To bulk-update all locally installed GRASS GIS extensions, g.exten‐
121 sion.all module is available.
122 Where the extensions are installed
124 GRASS GIS extensions are installed by g.extension into a dedicated di‐
125 rectory. The default is a directory for application data and settings
126 inside the user’s home directory. On GNU/Linux it is $HOME/.grass8/ad‐
127 dons, on MS-Windows it is %APPDATA%\Roaming\GRASS8\addons. The name of
128 the directory is stored in the GRASS_ADDON_BASE environmental variable.
129 The flag -s changes this install target directory to the GRASS GIS in‐
131 stallation directory (determined by GISBASE environmental variable,
132 e.g. /usr/) rather than the default directory defined as per GRASS_AD‐
133 DON_BASE (see also documentation for variables). g.extension checks if
134 the user has permission to write to GISBASE or GRASS_ADDON_BASE.
135 The place where the extensions are installed can be customized by the
137 option prefix. Ensuring that these extensions will be accessible in
138 GRASS GIS is in this case in the responsibility of the user.
139 Source code sources and repositories
141 GRASS GIS Addons repository on GitHub
142 By default, g.extension installs extensions from the official GRASS GIS
143 Addons GitHub repository. However, different sources can be specified
144 using the url option.
145 Individual extensions can also be installed by providing a URL to the
147 source code on GitHub or OSGeo Trac. The latter, however, works only
148 for certain directories where the download of ZIP files was enabled by
149 project administrators of the trac server.
150 Local source code directory
152 Optionally, new extension can be also installed from a source code
153 placed in a local directory on disk. This is advantageous when develop‐
154 ing a new module. To keep the directory clean, the directory content
155 is copied to a temporary directory and the compilation happens there.
156 Source code in a ZIP or TAR archive
158 In addition, new extension can be also installed from a ZIP file or an
159 archive file from the TAR family (e.g., .tar.gz or .bz2). The file can
160 be on disk (specified with a path), or on the web (specified by an
161 URL).
162 Online repositories: GitHub, GitLab and Bitbucket
164 For well known general hosting services, namely GitHub, GitLab and Bit‐
165 bucket, g.extension supports the download of a repository. Here the
166 user only needs to provide a base URL to the repository web page (with
167 or without the https:// part). For GitHub, GitLab and Bitbucket, the
168 latest source code in the default branch is downloaded, unless a spe‐
169 cific branch is requested in the branch option. Of course, a user can
170 still specify the full URL of a ZIP file e.g. for a specific release
171 and install the archived code in this way (ZIP file mechanism will be
172 applied).
173 For the official repository, g.extension supports listing available ex‐
175 tensions (addons) and few other metadata-related operations which de‐
176 pend on a specific infrastructure. For other sources and repositories,
177 this is not supported because it is assumed that other sources contain
178 only one extension, typically a module or group of modules with a Make‐
179 file at the root of the repository.
180 Needed directory layout
182 When none of the above sources is identified, g.extension assumes that
183 the source is in a GitHub repository and uses the git command line tool
184 to obtain the source code. The expected structure of the repository
185 should be the same as the one of the official repository.
186 Non-official sources are supported on all operating systems except for
188 MS-Windows.
189 Compilation and installation
191 On MS-Windows systems, where compilation tools are typically not read‐
192 ily locally installed, g.extension downloads a precompiled executable
193 from the GRASS GIS project server. On all other operating systems where
194 it is not difficult to install compilation tools, g.extension downloads
195 the source code of the requested extension (addon) and compiles it lo‐
196 cally. This applies for both C and Python modules as well as any other
197 extensions. The reason is that more things such as manual page are com‐
198 piled, not only the source code (which is really necessary to compile
199 just in case of C).
200
202 Download and install of an extension
203 Download and install r.stream.distance into current GRASS installation
204 g.extension extension=r.stream.distance
205 This installs the extension from the official repository. For conve‐
206 nience, a shorter syntax can be used:
207 g.extension r.stream.distance
208 Download and install of an extension when behind a proxy
210 Example for an open http proxy:
211 # syntax: http://proxyurl:proxyport
212 g.extension extension=r.stream.distance proxy="http=http://proxy.example.com:8080"
213 Example for a proxy with proxy authentication:
215 # syntax: http://username:password@proxyurl:proxyport
216 g.extension extension=r.stream.distance proxy="http=http://username:password@proxy.example.com:8080"
217 Managing the extensions
219 List all available extensions in the official GRASS GIS Addons reposi‐
220 tory:
221 g.extension -l
222 List all locally installed extensions:
223 g.extension -a
224 Removal of a locally installed extension:
225 g.extension extension=r.stream.distance operation=remove
226 Installing from various online repositories: GitHub, GitLab, Bitbucket
228 Simple URL to GitHub, GitLab, Bitbucket repositories:
229 g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus"
230 Simple URL to GitHub, GitLab, Bitbucket repositories from a specific
231 (e.g. development) branch:
232 g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus" branch=master
233 Simple URL to OSGeo Trac (downloads a ZIP file, requires download to be
234 enabled in Trac):
235 g.extension r.example url=trac.osgeo.org/.../r.example
236 In general, when a ZIP file or other archive is provided, the full URL
237 can be used:
238 g.extension r.example url=http://example.com/.../r.example?format=zip
239 Note that because of MS-Windows operating system architecture, only of‐
240 ficial repository is supported on this platform.
241 Install a specific version from Addons
243 To install a specific version from GRASS GIS Addons, specify the full
244 URL pointing to Trac code browser and include Subversion revision num‐
245 ber. For example, this installs the version number 57854 of r.local.re‐
246 lief module:
247 g.extension r.local.relief url="https://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.local.relief?rev=57854&format=zip"
248 Installing when writing a module locally
250 Having source code of a GRASS module in a directory on disk one can in‐
251 stall it using:
252 g.extension r.example url=/local/directory/r.example/
253
255 In order to clone source code repositories, the git command line tool
256 is required. The installation of single AddOns is most efficient with
257 versions of git that support so called sparse checkout, which was in‐
258 troduced with version 2.25. With older versions of git, the entire Ad‐
259 dOns repository will be downloaded. On UNIX like systems, installation
260 is done with the make command line tool. For AddOns written in C / C++,
261 a respective build environment is needed.
262
264 Toolboxes in the official repository cannot be downloaded.
265 On MS-Windows, only the official repository is working because there is
267 no way of compiling the modules (a Python replacement for Python
268 scripts should be implemented).
269
271 Since extensions have to be compiled on Unix based systems (Linux, Mac
272 OSX etc.) unless a Python extension is installed, a full compiler en‐
273 vironment must be present on the user’s computer.
274 ERROR: Please install GRASS development package
276 While GRASS GIS is available on the user’s computer, the respective de‐
277 velopment package is lacking. If GRASS was installed from a (Linux)
278 repository, also the grass-dev* package (commonly named "grass-dev" or
279 "grass-devel", sometimes along with the version number) must be in‐
280 stalled.
281
283 g.extension.all
284 GRASS GIS 8 Addons Manual pages
286 GRASS Addons wiki page.
287
289 Markus Neteler (original shell script)
290 Martin Landa, Czech Technical University in Prague, Czech Republic
291 (Python rewrite)
292 Vaclav Petras, NCSU OSGeoREL (support for general sources, partial
293 refactoring)
294
296 Available at: g.extension source code (history)
297 Accessed: Saturday Oct 28 18:19:19 2023
299 Main index | General index | Topics index | Keywords index | Graphical
301 index | Full index
302 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
304GRASS 8.3.1 g.extension(1)