QGIS Installer

To faciliate simple installation of the LUPTAI QGIS plugin, an installer has been developed using the Nullsoft Scriptable Install System (NSIS). Although QGIS has an in-built plugin repository and install system, this system does not support the installation of additional python packages, which are required for LUPTAI.

The installer script is located in the luptai_core repository at luptai_core/packaging/luptai_installer.nsi. The supporting files (and the code to be built into the installer) also live in the packaging directory.

Installer Process

  1. User selects the directory they have installed QGIS in (this allows the plugin to be installed to different QGIS versions, and does not rely on constants set in the registry).

  2. pip install the contents of packaging/luptai_python_dependencies/requirements.txt along with any included wheel files (these must be explicitly specified in the install script) into the qgis python. There are a couple of additional safety checks performed

    1. Attempt to invoke python at $InstallDir/apps/Python37/python.exe (check if python can be found in install location)

    2. Attempt to import the ssl module (some versions of QGIS are missing ssl dlls which can be installed separately with openssl light)

  3. User selects the QGIS plugin directory to install into (or accepts the default)

  4. Create plugin folder and copy the contents of packaging/luptai_qgis into $pluginDir

  5. Copy the contents of packaging/luptai_core into $pluginDir/luptai_core

  6. Copy the contents of packaging/luptai_dlls into $pluginDir/luptai_dlls

  7. Write config.json into $pluginDir with two keys “dll_path” and “core_path” which have corresponding values determined by the folder locations written to. This is so that these directories can be added to PYTHONPATH.

Building the installer

  1. Download and install NSIS

  2. Prepare contents of packaging folders according to above specification.

  3. Compile install script with NSIS and verify there are no errors

Alternatively, one may run packaging/deploy_and_build_installer.py with the appropriate flags set to automatically perform this process. This script also has capacity to silently install the plugin, provided the appropriate flags are set and it is run as administrator.

Installer Maintenance

As QGIS is updated it may become necessary to update portions of the installer so that they work correctly in new versions.

QGIS Python Path

The installer relies on a specific folder structure within the QGIS install location (which is specified by the user as part of the install process):

C:/Program Files/QGIS 3.xx/ (or C:/OSGEO4W/ or wherever you installed QGIS)
├── apps
│ └── Python37
│ └── python.exe

This structure is used to determine the location of the QGIS python executable. If this structure changes (i.e. a new version of QGIS updates to Python 3.8) then the corresponding constant must be updated.

!define QGIS_RELATIVE_PYTHON_FOLDER ="apps\Python37"

Default install location

The default install location of QGIS and the QGIS plugin directory may also be updated by updating following constants within the install script.

!define qgisDefaultInstallFolder "C:\Program Files\QGIS 3.10"
!define qgisDefaultPluginDir "$AppData\QGIS\QGIS3\profiles\default\python\plugins\"

Updating dependencies

As new versions of QGIS are released, the contents of packaging/luptai_python_dependencies/requirements.txt may need to be updated if there are package version conflicts or the base version of python in QGIS changes. The supplied wheels may also need to be updated to newer package versions. Any change to package versions should be followed by thorough testing to ensure that the plugin works as intended.

Developer Install

When developing the codebase it may be useful to see changes “live”, without needing to compile the installer. The following process allows one to use the live copy of code within a local luptai_core repository, rather than the latest deployed packaging code.

With elevated cmd (not powershell)

  1. cd %AppData%\QGIS\QGIS3\profiles\default\python\plugins\

  1. mklink /J luptai_qgis <PATH OF LUPTAI QGIS INSIDE CORE REPO INLCUDING THE qgis_plugin folder>

    e.g. mklink /J luptai_qgis C:\Data\Projects\20-050-Luptai\repo_folder\luptai_core\src\qgis_plugin

  2. make sure config.json in the root of qgis plugin is set correctly (it points to correct directories).

  3. Make sure plugin is enabled (and correct version is enabled) via the QGIS plugin manager