QGIS/doc/linux.t2t

= Building on GNU/Linux =

== Building QGIS with Qt 5.x ==

**Requires:** Ubuntu / Debian derived distro

/!\ **Note:** Refer to the section ''Building Debian packages'' for building
debian packages. Unless you plan to develop on QGIS, that is probably the
easiest option to compile and install QGIS.

These notes are for Ubuntu - other versions and Debian derived distros may
require slight variations in package names.

These notes are for if you want to build QGIS from source. One of the major
aims here is to show how this can be done using binary packages for ***all***
dependencies - building only the core QGIS stuff from source. I prefer this
approach because it means we can leave the business of managing system packages
to apt and only concern ourselves with coding QGIS!

This document assumes you have made a fresh install and have a 'clean' system.
These instructions should work fine if this is a system that has already been
in use for a while, you may need to just skip those steps which are irrelevant
to you.

== Prepare apt ==

The packages QGIS depends on to build are available in the "universe" component
of Ubuntu. This is not activated by default, so you need to activate it:

+ Edit your /etc/apt/sources.list file.
+ Uncomment all the lines starting with "deb"
+

Also you will need a recent enough distribution in order for all dependencies
to be met. The supported distributions are listed in the following section.

Now update your local sources database:

```
sudo apt-get update
```

== Install build dependencies ==

|| Distribution | install command for packages |
| buster | ``apt-get install bison ca-certificates ccache cmake cmake-curses-gui dh-python doxygen expect flex flip gdal-bin git graphviz grass-dev libexiv2-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl-dev libpq-dev libproj-dev libprotobuf-dev libqca-qt5-2-dev libqca-qt5-2-plugins libqscintilla2-qt5-dev libqt5opengl5-dev libqt5serialport5-dev libqt5sql5-sqlite libqt5svg5-dev libqt5webkit5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev libspatialindex-dev libspatialite-dev libsqlite3-dev libsqlite3-mod-spatialite libyaml-tiny-perl libzip-dev lighttpd locales ninja-build ocl-icd-opencl-dev opencl-headers pkg-config poppler-utils protobuf-compiler pyqt5-dev pyqt5-dev-tools pyqt5.qsci-dev python3-all-dev python3-autopep8 python3-dateutil python3-dev python3-future python3-gdal python3-httplib2 python3-jinja2 python3-lxml python3-markupsafe python3-mock python3-nose2 python3-owslib python3-plotly python3-psycopg2 python3-pygments python3-pyproj python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtsql python3-pyqt5.qtsvg python3-pyqt5.qtwebkit python3-requests python3-sip python3-sip-dev python3-six python3-termcolor python3-tz python3-yaml qt3d-assimpsceneimport-plugin qt3d-defaultgeometryloader-plugin qt3d-gltfsceneio-plugin qt3d-scene2d-plugin qt3d5-dev qt5-default qt5keychain-dev qtbase5-dev qtbase5-private-dev qtpositioning5-dev qttools5-dev qttools5-dev-tools saga spawn-fcgi txt2tags xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb`` |
| bionic | ``apt-get install bison ca-certificates ccache cmake cmake-curses-gui dh-python doxygen expect flex flip gdal-bin git graphviz grass-dev libexiv2-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl-dev libpq-dev libproj-dev libprotobuf-dev libqca-qt5-2-dev libqca-qt5-2-plugins libqscintilla2-qt5-dev libqt5opengl5-dev libqt5serialport5-dev libqt5sql5-sqlite libqt5svg5-dev libqt5webkit5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev libspatialindex-dev libspatialite-dev libsqlite3-dev libsqlite3-mod-spatialite libyaml-tiny-perl libzip-dev lighttpd locales ninja-build ocl-icd-opencl-dev opencl-headers pkg-config poppler-utils protobuf-compiler pyqt5-dev pyqt5-dev-tools pyqt5.qsci-dev python3-all-dev python3-autopep8 python3-dateutil python3-dev python3-future python3-gdal python3-httplib2 python3-jinja2 python3-lxml python3-markupsafe python3-mock python3-nose2 python3-owslib python3-plotly python3-psycopg2 python3-pygments python3-pyproj python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtsql python3-pyqt5.qtsvg python3-pyqt5.qtwebkit python3-requests python3-sip python3-sip-dev python3-six python3-termcolor python3-tz python3-yaml qt3d-assimpsceneimport-plugin qt3d-defaultgeometryloader-plugin qt3d-gltfsceneio-plugin qt3d-scene2d-plugin qt3d5-dev qt5-default qt5keychain-dev qtbase5-dev qtbase5-private-dev qtpositioning5-dev qttools5-dev qttools5-dev-tools saga spawn-fcgi txt2tags xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb`` |
| eoan | ``apt-get install bison ca-certificates ccache cmake cmake-curses-gui dh-python doxygen expect flex flip gdal-bin git graphviz grass-dev libexiv2-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl-dev libpq-dev libproj-dev libprotobuf-dev libqca-qt5-2-dev libqca-qt5-2-plugins libqscintilla2-qt5-dev libqt5opengl5-dev libqt5serialport5-dev libqt5sql5-sqlite libqt5svg5-dev libqt5webkit5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev libspatialindex-dev libspatialite-dev libsqlite3-dev libsqlite3-mod-spatialite libyaml-tiny-perl libzip-dev lighttpd locales ninja-build ocl-icd-opencl-dev opencl-headers pkg-config poppler-utils protobuf-compiler pyqt5-dev pyqt5-dev-tools pyqt5.qsci-dev python3-all-dev python3-autopep8 python3-dateutil python3-dev python3-future python3-gdal python3-httplib2 python3-jinja2 python3-lxml python3-markupsafe python3-mock python3-nose2 python3-owslib python3-plotly python3-psycopg2 python3-pygments python3-pyproj python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtsql python3-pyqt5.qtsvg python3-pyqt5.qtwebkit python3-requests python3-sip python3-sip-dev python3-six python3-termcolor python3-tz python3-yaml qt3d-assimpsceneimport-plugin qt3d-defaultgeometryloader-plugin qt3d-gltfsceneio-plugin qt3d-scene2d-plugin qt3d5-dev qt5-default qt5keychain-dev qtbase5-dev qtbase5-private-dev qtpositioning5-dev qttools5-dev qttools5-dev-tools saga spawn-fcgi txt2tags xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb`` |
| focal | ``apt-get install bison ca-certificates ccache cmake cmake-curses-gui dh-python doxygen expect flex flip gdal-bin git graphviz grass-dev libexiv2-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl-dev libpq-dev libproj-dev libprotobuf-dev libqca-qt5-2-dev libqca-qt5-2-plugins libqscintilla2-qt5-dev libqt5opengl5-dev libqt5serialport5-dev libqt5sql5-sqlite libqt5svg5-dev libqt5webkit5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev libspatialindex-dev libspatialite-dev libsqlite3-dev libsqlite3-mod-spatialite libyaml-tiny-perl libzip-dev lighttpd locales ninja-build ocl-icd-opencl-dev opencl-headers pkg-config poppler-utils protobuf-compiler pyqt5-dev pyqt5-dev-tools pyqt5.qsci-dev python3-all-dev python3-autopep8 python3-dateutil python3-dev python3-future python3-gdal python3-httplib2 python3-jinja2 python3-lxml python3-markupsafe python3-mock python3-nose2 python3-owslib python3-plotly python3-psycopg2 python3-pygments python3-pyproj python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtsql python3-pyqt5.qtsvg python3-pyqt5.qtwebkit python3-requests python3-sip python3-sip-dev python3-six python3-termcolor python3-tz python3-yaml qt3d-assimpsceneimport-plugin qt3d-defaultgeometryloader-plugin qt3d-gltfsceneio-plugin qt3d-scene2d-plugin qt3d5-dev qt5-default qt5keychain-dev qtbase5-dev qtbase5-private-dev qtpositioning5-dev qttools5-dev qttools5-dev-tools saga spawn-fcgi txt2tags xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb`` |
| sid | ``apt-get install bison ca-certificates ccache cmake cmake-curses-gui dh-python doxygen expect flex flip gdal-bin git graphviz grass-dev libexiv2-dev libexpat1-dev libfcgi-dev libgdal-dev libgeos-dev libgsl-dev libpq-dev libproj-dev libprotobuf-dev libqca-qt5-2-dev libqca-qt5-2-plugins libqscintilla2-qt5-dev libqt5opengl5-dev libqt5serialport5-dev libqt5sql5-sqlite libqt5svg5-dev libqt5webkit5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev libspatialindex-dev libspatialite-dev libsqlite3-dev libsqlite3-mod-spatialite libyaml-tiny-perl libzip-dev lighttpd locales ninja-build ocl-icd-opencl-dev opencl-headers pkg-config poppler-utils protobuf-compiler pyqt5-dev pyqt5-dev-tools pyqt5.qsci-dev python3-all-dev python3-autopep8 python3-dateutil python3-dev python3-future python3-gdal python3-httplib2 python3-jinja2 python3-lxml python3-markupsafe python3-mock python3-nose2 python3-owslib python3-plotly python3-psycopg2 python3-pygments python3-pyproj python3-pyqt5 python3-pyqt5.qsci python3-pyqt5.qtsql python3-pyqt5.qtsvg python3-pyqt5.qtwebkit python3-requests python3-sip python3-sip-dev python3-six python3-termcolor python3-tz python3-yaml qt3d-assimpsceneimport-plugin qt3d-defaultgeometryloader-plugin qt3d-gltfsceneio-plugin qt3d-scene2d-plugin qt3d5-dev qt5-default qt5keychain-dev qtbase5-dev qtbase5-private-dev qtpositioning5-dev qttools5-dev qttools5-dev-tools saga spawn-fcgi txt2tags xauth xfonts-100dpi xfonts-75dpi xfonts-base xfonts-scalable xvfb`` |

(extracted from the control.in file in ``debian/``)

See http://qgis.org/en/site/forusers/alldownloads.html#debian-ubuntu for
currently supported distributions (plain xenial's GDAL for instance is to old
and we build with GDAL2 from ubuntugis).


== Setup ccache (Optional, but recommended) ==

You should also setup ccache to speed up compile times:

```
cd /usr/local/bin
sudo ln -s /usr/bin/ccache gcc
sudo ln -s /usr/bin/ccache g++
```

or simply add ``/usr/lib/ccache`` to your ``PATH``.

== Prepare your development environment ==

As a convention I do all my development work in $HOME/dev/<language>, so in
this case we will create a work environment for C++ development work like
this:

```
mkdir -p ${HOME}/dev/cpp
cd ${HOME}/dev/cpp
```

This directory path will be assumed for all instructions that follow.


== Check out the QGIS Source Code ==

There are two ways the source can be checked out. Use the anonymous method
if you do not have edit privileges for the QGIS source repository, or use
  the developer checkout if you have permissions to commit source code
  changes.

1. Anonymous Checkout

```
cd ${HOME}/dev/cpp
git clone git://github.com/qgis/QGIS.git
```

2. Developer Checkout

```
cd ${HOME}/dev/cpp
git clone git@github.com:qgis/QGIS.git
```

== Starting the compile ==

I compile my development version of QGIS into my ~/apps directory to avoid
conflicts with Ubuntu packages that may be under /usr. This way for example
you can use the binary packages of QGIS on your system along side with your
development version. I suggest you do something similar:

```
mkdir -p ${HOME}/apps
```

Now we create a build directory and run ccmake:

```
cd QGIS
mkdir build-master
cd build-master
ccmake ..
```

When you run ccmake (note the .. is required!), a menu will appear where
you can configure various aspects of the build. If you want QGIS to have
debugging capabilities then set CMAKE_BUILD_TYPE to Debug. If you do not have
root access or do not want to overwrite existing QGIS installs (by your
package manager for example), set the CMAKE_INSTALL_PREFIX to somewhere you
have write access to (I usually use ${HOME}/apps). Now press
'c' to configure, 'e' to dismiss any error messages that may appear.
and 'g' to generate the make files. Note that sometimes 'c' needs to
be pressed several times before the 'g' option becomes available.
After the 'g' generation is complete, press 'q' to exit the ccmake
interactive dialog.

/!\ **Warning:** Make sure that your build directory is completely empty when you
enter the command. Do never try to "re-use" an existing **Qt5** build directory.
If you want to use `ccmake` or other interactive tools, run the command in
the empty build directory once before starting to use the interactive tools.

Now on with the build:

```
make -jX
```

where X is the number of available cores. Depending on your platform,
this can speed up the build time considerably.

Then you can directly run from the build directory:

```
./output/bin/qgis
```

Another option is to install to your system:

```
make install
```

After that you can try to run QGIS:

```
$HOME/apps/bin/qgis
```

If all has worked properly the QGIS application should start up and appear
on your screen. If you get the error message "error while loading shared libraries",
execute this command in your shell.

```
sudo ldconfig
```

If that doesn't help add the install path to LD_LIBRARY_PATH:


```
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${HOME}/apps/lib/
```

Optionally, if you already know what aspects you want in your custom build
then you can skip the interactive ccmake .. part by using the cmake -D
option for each aspect, e.g.:

```
cmake -D CMAKE_BUILD_TYPE=Debug -D CMAKE_INSTALL_PREFIX=${HOME}/apps ..
```

Also, if you want to speed your build times, you can easily do it with ninja,
an alternative to make with similar build options.

For example, to configure your build you can do either one of:

```
ccmake -G Ninja ..
```

```
cmake -G Ninja -D CMAKE_BUILD_TYPE=Debug -D CMAKE_INSTALL_PREFIX=${HOME}/apps ..
```

Build and install with ninja:

```
ninja (uses all cores by default; also supports the above described -jX option)
ninja install
```

To build even faster, you can build just the targets you need using, for example:
```
ninja qgis
ninja pycore
# if it's on desktop related code only:
ninja qgis_desktop
```

== Compiling with 3D ==

In the cmake, you need to enable:
```
WITH_3D=True
```
=== Compiling with 3D on Debian based distributions ===

QGIS 3D requires Qt53DExtras. These headers have been removed
from Qt upstream on Debian based distributions. A copy has been made in the
QGIS repository in ``external/qt3dextra-headers``.
To compile with 3D enabled, you need to add some cmake options:
```
CMAKE_PREFIX_PATH={path to QGIS Git repo}/external/qt3dextra-headers/cmake
QT5_3DEXTRA_INCLUDE_DIR={path to QGIS Git repo}/external/qt3dextra-headers
QT5_3DEXTRA_LIBRARY=/usr/lib/x86_64-linux-gnu/libQt53DExtras.so
```

== Building different branches ==

By using ``git worktree``, you can switch between different branches to use
several sources in parallel, based on the same Git configuration.
We recommand you to read the documentation about this Git command:
```
git commit
git worktree add ../my_new_functionality
cd ../my_new_functionality
git fetch qgis/master
git rebase -i qgis/master
# only keep the commits to be pushed
git push -u my_own_repo my_new_functionality
```

== Building Debian packages ==

Instead of creating a personal installation as in the previous step you can
also create debian package. This is done from the QGIS root directory, where
you'll find a debian directory.

First you need to install the debian packaging tools once:

```
apt-get install build-essential
```

First you need to create an changelog entry for your distribution. For example
for Ubuntu Precise:

```
dch -l ~precise --force-distribution --distribution precise "precise build"
```

The QGIS packages will be created with:

```
dpkg-buildpackage -us -uc -b
```

/!\ **Note:** Install ``devscripts`` to get ``dch``.

/!\ **Note:** If ``dpkg-buildpackage`` complains about unmet build dependencies
you can install them using ``apt-get`` and re-run the command.

/!\ **Note:** If you have ``libqgis1-dev`` installed, you need to remove it first
using ``dpkg -r libqgis1-dev``.  Otherwise ``dpkg-buildpackage`` will complain about a
build conflict.

/!\ **Note:** By default tests are run in the process of building and their
results are uploaded to http://cdash.orfeo-toolbox.org/index.php?project=QGIS.
You can turn the tests off using DEB_BUILD_OPTIONS=nocheck in front of the
build command. The upload of results can be avoided with DEB_TEST_TARGET=test.

The packages are created in the parent directory (ie. one level up).
Install them using dpkg.  E.g.:

```
sudo debi
```

== On Fedora Linux ==

We assume that you have the source code of QGIS ready and created a
new subdirectory called `build` or `build-qt5` in it.

=== Install build dependencies ===

```
dnf install qt5-qtbase-private-devel qt5-qtwebkit-devel qt5-qtlocation-devel qt5-qttools-static qca-qt5-devel qca-qt5-ossl qt5-qt3d-devel python3-qt5-devel python3-qscintilla-qt5-devel qscintilla-qt5-devel python3-qscintilla-devel python3-qscintilla-qt5 clang flex bison geos-devel gdal-devel sqlite-devel libspatialite-devel qt5-qtsvg-devel spatialindex-devel expat-devel proj-devel qwt-qt5-devel gsl-devel postgresql-devel cmake python3-future gdal-python3 python3-psycopg2 python3-PyYAML python3-pygments python3-jinja2 python3-OWSLib qca-qt5-ossl qwt-qt5-devel qtkeychain-qt5-devel qwt-devel sip-devel libzip-devel exiv2-devel
```

To build QGIS server additional dependencies are required:

```
dnf install fcgi-devel
```

Make sure that your build directory is completely empty when you enter the
following command. Do never try to "re-use" an existing Qt5 build directory.
If you want to use `ccmake` or other interactive tools, run the following
command in the empty build directory once before starting to use the interactive
tools.

```
cmake ..
```

If everything went OK you can finally start to compile. (As usual append a -jX
where X is the number of available cores option to make to speed up your build
process)

```
make
```

Run from the build directory

```
./output/bin/qgis
```

Or install to your system


```
make install
```

=== Suggested system tweaks ===

By default Fedora disables debugging calls from Qt applications. This prevents
the useful debug output which is normally printed when running the unit tests.

To enable debug prints for the current user, execute:

```
cat > ~/.config/QtProject/qtlogging.ini << EOL
[Rules]
default.debug=true
EOL
```