|
NAMEg.extension - Maintains GRASS Addons extensions in local GRASS installation.Downloads and installs extensions from GRASS Addons repository or other source into the local GRASS installation or removes installed extensions. KEYWORDSgeneral, installation, extensions, addons, downloadSYNOPSISg.extensiong.extension --help g.extension [-lcgasdiftoj] extension=name operation=string [url=url] [prefix=path] [proxy=proxy[,proxy,...]] [branch=branch] [--help] [--verbose] [--quiet] [--ui] Flags:
Parameters:
DESCRIPTIONg.extension downloads and installs, removes or updates extensions (addons) from the official GRASS GIS Addons repository or from user-specified source code repositories into the local GRASS GIS installation.Two types of extensions are supported:
Managing installed extensionsRe-running g.extension on an installed GRASS GIS Addon extension re-installs the requested extension which may include updates.To bulk-update all locally installed GRASS GIS extensions, g.extension.all module is available. Where the extensions are installedGRASS GIS extensions are installed by g.extension into a dedicated directory. The default is a directory for application data and settings inside the user’s home directory. On GNU/Linux it is $HOME/.grass7/addons, on MS-Windows it is $APPDATA\GRASS7\addons. The name of the directory is stored in the GRASS_ADDON_BASE environmental variable.The flag -s changes this install target directory to the GRASS GIS installation directory (determined by GISBASE environmental variable, e.g. /usr/) rather than the default directory defined as per GRASS_ADDON_BASE (see also documentation for variables). g.extension checks if the user has permission to write to GISBASE or GRASS_ADDON_BASE. The place where the extensions are installed can be customized by the option prefix. Ensuring that these extensions will be accessible in GRASS GIS is in this case in the responsibility of the user. Source code sources and repositoriesGRASS GIS Addons repository on GitHubBy default, g.extension installs extensions from the official GRASS GIS Addons GitHub repository. However, different sources can be specified using the url option.Individual extensions can also be installed by providing a URL to the source code on GitHub or OSGeo Trac. The latter, however, works only for certain directories where the download of ZIP files was enabled by project administrators of the trac server. Local source code directoryOptionally, new extension can be also installed from a source code placed in a local directory on disk. This is advantageous when developing a new module. To keep the directory clean, the directory content is copied to a temporary directory and the compilation happens there.Local source code ZIP fileIn addition, new extension can be also installed from a ZIP file or an archive file from the TAR family (e.g., .tar.gz or .bz2). The file can be on disk (specified with a path), or on web (specified by an URL).Online repositories: GitHub, GitLab and BitbucketFor well known general hosting services, namely GitHub, GitLab and Bitbucket, g.extension supports the download of a repository as a ZIP file. Here the user only needs to provide a base URL to the repository web page (with or without the https:// part). For GitLab and Bitbucket, the latest source code in the default branch is downloaded, for GitHub, the latest source code in the master branch is downloaded. Of course, a user can still specify the full URL of a ZIP file and install a specific branch or release in this way (ZIP file mechanism will be applied).For the official repository, g.extension supports listing available extensions (addons) and few other metadata-related operations which depend on a specific infrastructure. For other sources and repositories, this is not supported because it is assumed that other sources contain only one extension, typically a module or group of modules. Needed directory layoutWhen none of the above sources is identified, g.extension assumes that the source is in a GitHub repository and uses the svn command line tool to obtain the source code. The expected structure of the repository should be the same as the one of the official repository.Non-official sources are supported on all operating systems except for MS-Windows. Compilation and installationOn MS-Windows systems, where compilation tools are typically not readily locally installed, g.extension downloads a precompiled executable from the GRASS GIS project server. On all other operating systems where it is not difficult to install compilation tools, g.extension downloads the source code of the requested extension (addon) and compiles it locally. This applies for both C and Python modules as well as any other extensions. The reason is that more things such as manual page are compiled, not only the source code (which is really necessary to compile just in case of C).EXAMPLESDownload and install of an extensionDownload and install r.stream.distance into current GRASS installationg.extension extension=r.stream.distanceThis installs the extension from the official repository. For convenience, a shorter syntax can be used: g.extension r.stream.distance Download and install of an extension when behind a proxyExample for an open http proxy:# syntax: http://proxyurl:proxyport g.extension extension=r.stream.distance proxy="http=http://proxy.example.com:8080" Example for a proxy with proxy authentication:
# syntax: http://username:password@proxyurl:proxyport g.extension extension=r.stream.distance proxy="http=http://username:password@proxy.example.com:8080" Managing the extensionsList all available extensions in the official GRASS GIS Addons repository:g.extension -lList all locally installed extensions: g.extension -aRemoval of a locally installed extension: g.extension extension=r.stream.distance operation=remove Installing from various online repositories: GitHub, GitLab, BitbucketSimple URL to GitHub, GitLab, Bitbucket repositories:g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus"Simple URL to GitHub, GitLab, Bitbucket repositories from a specific (e.g. development) branch: g.extension r.example.plus url="https://github.com/wenzeslaus/r.example.plus" branch=masterSimple URL to OSGeo Trac (downloads a ZIP file, requires download to be enabled in Trac): g.extension r.example url=trac.osgeo.org/.../r.exampleIn general, when a ZIP file or other archive is provided, the full URL can be used: g.extension r.example url=http://example.com/.../r.example?format=zipNote that because of MS-Windows operating system architecture, only official repository is supported on this platform. Install a specific version from AddonsTo install a specific version from GRASS GIS Addons, specify the full URL pointing to Trac code browser and include Subversion revision number. For example, this installs the version number 57854 of r.local.relief module:g.extension r.local.relief url="https://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.local.relief?rev=57854&format=zip" Installing when writing a module locallyHaving source code of a GRASS module in a directory on disk one can install it using:g.extension r.example url=/local/directory/r.example/ KNOWN ISSUESToolboxes in the official repository cannot be downloaded.On MS-Windows, only the official repository is working because there is no way of compiling the modules (a Python replacement for Python scripts should be implemented). TROUBLESHOOTINGSince extensions have to be compiled on Unix based systems (Linux, Mac OSX etc.) unless a Python extension is installed, a full compiler environment must be present on the user’s computer.ERROR: Please install GRASS development packageWhile GRASS GIS is available on the user’s computer, the respective development package is lacking. If GRASS was installed from a (Linux) repository, also the grass-dev* package (commonly named "grass-dev" or "grass-devel", sometimes along with the version number) must be installed.SEE ALSOg.extension.allGRASS GIS 7 Addons Manual pages
AUTHORSMarkus Neteler (original shell script)Martin Landa, Czech Technical University in Prague, Czech Republic (Python rewrite) Vaclav Petras, NCSU OSGeoREL (support for general sources, partial refactoring) SOURCE CODEAvailable at: g.extension source code (history)Main index | General index | Topics index | Keywords index | Graphical index | Full index © 2003-2021 GRASS Development Team, GRASS GIS 7.8.6 Reference Manual
Visit the GSP FreeBSD Man Page Interface. |