install_guide.Rmd

---
title: "(R)QGIS3 installation guide for Windows, Mac & Linux"
author: "Jannes Muenchow, Patrick Schratz"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{(R)QGIS3 installation guide for Windows, Mac & Linux"}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  #fig.path = "https://raw.githubusercontent.com/jannes-m/RQGIS/master/figures/",
  fig.align = "center",
  collapse = TRUE,
  comment = "#>"
)
```


# Vignette info
This vignette guides you through the installation process of QGIS3, GRASS- and SAGA-GIS on three different platforms (Windows, Mac, Linux). 
Please use the QGIS3 long-term release.
Following our instructions should ensure that **RQGIS3** will work properly. 
With the exception of SAGA, we recommend to use the latest stable version of all software packages. 
Though other versions might also work with **RQGIS3**, we did not test this.

Overall, **RQGIS3** allows access to almost 1000 geoalgorithms.
However, please note that the number of geoalgorithms you can use from within **RQGIS3** depends on the platform, the system architecture, the selection of installed third-party providers and software package versions.

# Windows

There are at least two options to install QGIS on Windows in such a way that **RQGIS3** can access QGIS.
The first option is the Standalone Installer from the [QGIS installer page](https://www.qgis.org/en/site/forusers/download.html). 
This will install QGIS3 along with the third-party providers GRASS and SAGA, and most likely will meet the needs of most users.
However, if you would like to install specific software versions and use even more third-party providers, use the OSGeo4W Network installer. 
This installer is available on the [QGIS installer page](https://www.qgis.org/en/site/forusers/download.html) as well as on the [OSGeo4W-website](http://trac.osgeo.org/osgeo4w/). 
Download it and follow the instructions when executing the installer.

# Linux

## Ubuntu

### QGIS3 (and GRASS)
If you install QGIS3 with the built-in software managers, you will most likely get an outdated QGIS3 version. 
To install more recent QGIS3 releases, we recommend to follow the installation instructions from the [QGIS3 installers website](https://www.qgis.org/en/site/forusers/alldownloads.html). 

Here, we just describe exemplarily the QGIS3 installation procedure under Debian/Ubuntu following the description found [here](https://www.qgis.org/en/site/forusers/alldownloads.html#debian-ubuntu).
**RQGIS3** should also work with Linux derivatives other than Ubuntu.
However, we did not test this.

Open a terminal window. 
First of all, make sure to remove QGIS3 and GRASS packages you may have installed before from other repositories:

<!--http://gis.stackexchange.com/questions/167472/qgis-2-8-ubuntu-14-04-installation-issues-terminal-command-attempts-to-install-->
```sh 
sudo apt-get --purge remove qgis
sudo apt autoremove
sudo apt-get update
```

Next add the correct repository to `/etc/apt/sources.list`.
Here, we use the current long-term release.
To also install GRASS7, we have to add the ubuntugis-unstable ppa repository.

**QGIS 3.x for Ubuntu 18.04**

```sh
# add QGIS repository for Ubuntu 18.04 to sources.list
sudo sh -c 'echo "deb http://qgis.org/ubuntu-ltr bionic main" >> /etc/apt/sources.list'
sudo sh -c 'echo "deb-src http://qgis.org/ubuntu-ltr bionic main" >> /etc/apt/sources.list'
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
```

**QGIS 3.x for Ubuntu 16.04**

Since `xenial` lacks a native `gdal2` installation, we will use the "ubuntugis" repos including its "ubuntugis-unstable" repo (for `gdal2`) to install QGIS.

```sh
# add QGIS repository for Ubuntu 16.04 to sources.list
sudo sh -c 'echo "deb http://qgis.org/ubuntugis xenial main" >> /etc/apt/sources.list'
sudo sh -c 'echo "deb-src http://qgis.org/ubuntugis xenial main" >> /etc/apt/sources.list'
sudo sh -c 'echo "deb http://ppa.launchpad.net/ubuntugis/ubuntugis-unstable/ubuntu xenial main" >> /etc/apt/sources.list'
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
```

**For other Ubuntu releases, simply replace 'xenial' with the respective release name.**

Next we need to add the GPG key to avoid key errors:

```sh
wget -O - https://qgis.org/downloads/qgis-2019.gpg.key | gpg --import
# verify fingerprint
gpg --fingerprint 51F523511C7028C3
gpg --export --armor 51F523511C7028C3 | sudo apt-key add -
```

After that, we can install QGIS3 and GRASS as follows:

```sh
sudo apt-get update
sudo apt-get install qgis python-qgis qgis-plugin-grass
```

### SAGA

SAGA's current long term release is 7.3.
Until now, QGIS3 only supports SAGA versions 2.3.x.
In the meantime, however, SAGA 2.3.x is no longer actively developed, and depends on old gdal and proj libraries which conflict with those used by QGIS3 and GRASS7.
Therefore, we can only suggest to wait until QGIS3 also supports a more recent version of SAGA. 
Please note that under Debian which is not using the ubuntugis-unstable repository, one can still use SAGA 2.3.1 and QGIS3 and GRASS7 (see the [geocompr-dockerfile](https://github.com/Robinlovelace/geocompr/blob/master/Dockerfile) for an example).
So in the meantime, we can offer this [Docker image](https://hub.docker.com/r/robinlovelace/geocompr/) available on docker hub as an alternative to be able to use SAGA also with QGIS3.
Please see the [geocompr landing page](https://github.com/Robinlovelace/geocompr/#running-geocompr-code-in-docker) for further instructions how to use it.

<!--
Under Ubuntu we need to install GRASS-GIS7 from ppa:ubuntugis/ubuntugis-unstable.
In this repo, we also find SAGA 7.3 which is until not supported by QGIS3.
Compiling SAGA manually, see below, did install SAGA 2.3.1 but it could not be used from within QGIS3.
-->

<!---

You can install the SAGA LTS 2.3.1 version from the [ubuntugis/unstable](https://launchpad.net/~ubuntugis/+archive/ubuntu/ubuntugis-unstable) repository.
If you haven't done so yet, add the repository and then simply install SAGA via `apt-get`:

```sh
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install saga
```

To use SAGA functions within (R)QGIS, you naturally need to install SAGA GIS. To install the most recent SAGA version, simply execute the following lines in a terminal window: 

```sh
sudo add-apt-repository ppa:johanvdw/saga-gis  
sudo apt-get update
sudo apt-get install saga
```
sudo add-apt-repository --remove ppa:johanvdw/saga-gis


As far as we know, QGIS currently only supports the old SAGA versions 2.3.x (current SAGA version is 7.3).
To install old SAGA versions, we need to download and compile it manually (see [here](https://sourceforge.net/p/saga-gis/wiki/Compiling%20SAGA%20on%20Linux/)). 

Prior to the SAGA installation, we need to install various dependencies required by SAGA.
Here, we just quickly show how to install SAGA and its dependencies under Ubuntu. 
Please refer to this [page](https://sourceforge.net/p/saga-gis/wiki/Compiling%20SAGA%20on%20Linux/) for a more comprehensive SAGA installation guide.
Please note that we here simply reproduce great parts of this guide.

First of all, install all necessary SAGA dependencies and a few compilation and configuration tools:

```sh
sudo apt-get install libwxgtk3.0-dev libtiff5-dev libgdal-dev libproj-dev \
    libexpat-dev wx-common libogdi3.2-dev unixodbc-dev

# compilation and configuration tools
sudo apt-get install g++ make automake libtool git
```

Next, we would like to download a specific SAGA version. 
Check out the various available versions [here](https://sourceforge.net/projects/saga-gis/files/). 
Here, we will download SAGA 2.3.1 into our home directory, unpack it and change the working directory to the unpacked folder:

```sh
wget -O /home/$USER/saga-git "https://sourceforge.net/projects/saga-gis/files/SAGA%20-%202/SAGA%202.3.1/saga_2.3.1.tar.gz/download"
cd "/home/$USER"
sudo tar -xvzf saga-git
cd saga-2.3.1
```
Having done so, we are ready to compile SAGA (which takes a while...):

```sh
sudo autoreconf -i
sudo ./configure
sudo make
sudo make install
```

To check if SAGA was successfully compiled, run:

```
saga_cmd
saga_gui
```

Sometimes `saga_gui` produces following error message:

```sh
saga_gui: error while loading shared libraries: libsaga_gdi-2.3.1.so: cannot open shared object file: No such file or directory
```
In this case, you have to enable the SAGA GUI by specifying the path where `libsaga_gdi-2.3.1.so` is located:
```sh
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
saga_gui
```

After the installation you will find the SAGA algorithms in the processing toolbox of the QGIS GUI (this might not be true for SAGA >= 2.2.1 see further below). 


Using SAGA >= 2.2.1 you might encounter following message in the Processing log when opening QGIS: 
`Problem with SAGA installation: installed SAGA version (2.3.1) is not supported`. 
Though in this case SAGA is not available in the processing toolbox, you might still able to use it 
via the QGIS Python API and therefore also with RQGIS.
Please note that SAGA 2.3.1 is the latest SAGA version supported by QGIS (2.14 and 2.18).

In case you would like to uninstall SAGA, type:

```sh
cd "/home/$USER/saga-2.3.1"
sudo make uninstall
```

### Orfeo Toolbox (OTB)

You can download the Orfeo Toolbox from [here](https://www.orfeo-toolbox.org/download/).
We save the .run-script to the Desktop. Of course, you might select any other accesible folder.
Next, we create a folder named "Applications" to which we move the .run script. Finally, we install OTB. 
Please note that so far there is only a **64-bit** OTB version available.
This version does not work on 32-bit machines!

```sh
mkdir /home/<YourUserName>/Applications/
mv /home/<YourUserName>/Desktop/<filename> /home/<YourUserName>/Applications
sh /home/<YourUserName>/Applications/<NameOfScript>
```
(R)QGIS assumes that the "OTB applications folder" is located at "/usr/lib/otb/applications" (see also [QGIS manual](https://docs.qgis.org/2.14/en/docs/user_manual/processing/3rdParty.html#orfeo-toolbox)). 
Therefore, we need to move the OTB installation to the corresponding folder: 

```sh
# move applications folder
sudo mv /home/<YourUserName>/Applications/<YourOTBInstallation>/lib/otb /usr/lib/
# commandline tools
cp -a /home/<YourUserName>/Applications/<YourOTBInstallation>/bin/. /usr/bin
```
OTB algorithms should be now availabe in the "Processing Toolbox" and in RQGIS (use `find_algorithms()` to check). 
Finally, we clean up after ourselves by deleting the previously created Applications folder:

```sh
rmdir /home/<YourUserName>/Applications/
```
--> 

## Arch Linux

You can install various QGIS and GRASS versions from the [Arch User Repository](https://aur.archlinux.org/). 
We recommend to use the [yaourt](https://wiki.archlinux.de/title/Yaourt) package manager.
At the moment it is not possible to use SAGA in conjunction with QGIS3 on Arch-based OS.
Please use the [geocompr docker image](https://hub.docker.com/r/robinlovelace/geocompr/) as described in the previous section.

# Mac OS X

## SAGA

There is no binary install of SAGA for macOS.
We recommend to use the bottle installation from `homebrew`:

```sh
# brew tap osgeo4mac
brew install osgeo-saga-gis-lts
brew link --force osgeo-saga-gis-lts
```

If you do not link SAGA with force, QGIS will not be able to detect SAGA.

Alternatively, you can compile SAGA from source from the [SAGA website](https://sourceforge.net/projects/saga-gis/files/). 
However, this is tedious and QGIS only supports the SAGA LTS version.

## GRASS

You can install GRASS7 via `homebrew`:

```sh
# brew tap osgeo4mac
brew install osgeo-grass7
```

The binary GRASS installation can be found [here](https://grass.osgeo.org/download/software/mac-osx/). 
However, we recommend to use the `homebrew` approach.

When installing GRASS7 independently of QGIS via `homebrew`, please make sure to install it **before** you have installed QGIS.
Only this way, the path for the QGIS processing plugin will be updated.
Otherwise, the GRASS installation will work, however, `GRASS7Utils.grassPath()`, a QGIS function that links to the GRASS installation, gives back a non-existing path such as `/Applications/Grass-7.0.app/Contents/MacOS` which in turn prevents GRASS algorithms from working from within QGIS.

## QGIS

Two options exist installing QGIS on macOS

1. Using `homebrew` (**recommended**)

```
# brew tap osgeo/osgeo4mac
brew install osgeo-qgis-ltr
```

Check `brew info osgeo-qgis` for more available options. 
However, if you use them, QGIS will be compiled from source which may take > 30 min (depending on your system).
Otherwise, pre-built bottles (= binaries) will be used which speeds up the installation process a lot.

**Note:** Make sure to install SAGA and GRASS before QGIS so that QGIS finds the correct paths.

2. Using the official QGIS binary

We currently do not support the QGIS installer from https://www.qgis.org/en/site/forusers/download.html  due to technical issues getting it working with **RQGIS3**.
We may add support for it in the future.