This document explains how to set up a basic development environment for the Swedigarch QGIS plugins. These plugins are a set of tools that allow you to work with Intrasis archaeological datasets. You can use the plugins to export Intrasis databases as geopackages, and to analyse and export data in various formats using QGIS and the Swedigarch plugins.
The Swedigarch plugins consist of Intrasis DB Manager, Intrasis Class/SubClass Browser, and Intrasis Relationship Browser. Each part in the plugin has its own readme file that describes its features and functions.
The Swedigarch plugins have been developed and tested against QGIS version 3.28 through 3.32.
This section describes how to set up a basic development environment under Windows.
A basic development environment consists of the following components:
- A complete QGIS installation (with QT tools, OSWGEO4 Shell, etc.)
- A code editor that is compatible with GIT
- Access to a GIT code repository
- At least one sample Intrasis Database and/or a sample Intrasis Geopackage (The sample data is needed for testing purposes).
The Swedigarch plugin is used to export and analyze data from an Intrasis Database. To set up a Postgres Server and recreate an Intrasis Database for testing and development purposes, see the section Recreate Intrasis Database.
A basic plugin template can be generated by using the Plugin Builder tool. The Plugin Reloader tool can be used to reload a plugin and reflect the changes made during development.
The development of the Swedigarch plugin was done using Visual Studio Code. The code editor and the GIT tools were used to manage the code changes and clone the plugin code repository to a local folder.
This workflow was used during development of the plugins (Azure DevOps was used but the workflow can be adapted to other code development platforms):
To do a first quality assurance, we conduct a code review of each other and follow the following routine:
- We tag the commit with PBI/task ID to link the commit to it. For example, 33278 Save symbolism for the different layers (metadata)
- We write a comment and explain how/what can be tested in the PBI/task. It is important to remember to tag the other members so they get a notice about this.
- We leave a comment/create a bug if necessary.
- If everything looks good, drag the PBI/task to closed and then finish the code review.
- Done!
QGIS plugins are installed in the user profile of QGIS. It can be more convenient to work on a path elsewhere when developing the plugin. One reason to not work directly in the user profile is to avoid any changes in that location made by QGIS. For example the plugin could get uninstalled by user mistake. By using Link Shell Extension and creating a link, we can keep our code under the development directory we want without having to work directly under the user profile. We create a symbolic link to the path where the GIT repository is downloaded. For further and up to date information on QGIS plugin development please refer to QGIS documentation."Link Shell Extension" can be found here https://schinagl.priv.at/nt/hardlinkshellext/linkshellextension.html
resources.qrc contains the paths to the image files that are used by the plugin. If resources.qrc is edited or if the files in the paths are edited i.e. an image is replaced or edited resources.qrc needs to be compiled so that resources.py is regenerated. The process to compile resources.qrc is as follows:
#Using OSGEO4W shell
#compile with pyrcc5
pyrcc5 resources.qrc -o resources.py#If it fails, maybe the environment is not correctly set up
#To set up environment OSGEO4W shell try:
py3_env
qt5_envAn alternative way to compile is to use rcc.exe from FreeCAD
One way to get hold of rcc.exe is to download and install FreeCAD (Opens in new window or tab) Once you have installed it, you have got an rcc.exe in FreeCAD’s bin directory. You can run the compiler, for example with this command in the plugin directory (the directory that has the files resources.qrc and resources.py).
"C:\Program Files\FreeCAD 0.20\bin\rcc.exe” -g python -compress-algo zlib -compress 9 --verbose resources.qrc > resources.py After that, you need to edit resources.py and replace PySide2 with PyQt5
Workflow create translation support. To create translation support, QTLinguist is used. By translation support we mean the function in QGIS that automatically changes the language in the user interface according to the selected language in QGIS Settings -> Options. The files used to enable translation support for the plugin are in the folder:
\swedigarch_plugin\i18n\
Example of files that are needed: SvedigarkDbManager.pro swedigarch_db_mgr_sv_SE.qm swedigarch_db_mgr_sv_SE.ts
The file SvedigarkDbManager.pro contains the paths to the plugin’s source code files of type *.ui, *.py and *.ts. For the translation to work, SvedigarkDbManager.pro needs to be updated with correct paths if you add or remove source code files from the project. The principle of the translation support is that in the plugin’s Python code self.tr() is added, the QTLinguist tools looks for the lines with self.tr() and generates the conditions for translation.
-
- Put self.tr() in the code: Example:
textTest = self.tr('Connected to Database')
self.lineEdit_DbConnection.setText(f"{textTest} {self.host}")Note that the text was assigned to a variable, which has been the only way to get it working when using f-string or formatted string literal.
# Failed to be translated
lineEdit_DbConnection.setText(f"{self.tr('Connected to')} {self.host}")-
- Use OSGeo4W Shell:
pylupdate5.exe -verbose "[path to i18n]\IntrasisDBManager.pro"
# Updating 'intrasis_db_mgr_en_US.ts'...
Found 55 source texts (2 new and 53 already existing)
# Updating 'intrasis_db_mgr_sv.ts'...
Found 55 source texts (2 new and 53 already existing)-
- Type: linguist.exe in OSGeo4W Shell and use the GUI to edit translations
-
- Run lrelease in
C:\standalone\QtLinguist-Standalone-5.12.0\QtLinguist\bin
[path to QtLinguist-Standalone]\bin\lrelease.exe [path to i18n]\intrasis_db_mgr_sv.ts
[path to QtLinguist-Standalone]\bin\lrelease.exe [path to i18n]\intrasis_db_mgr_en_US.ts-
- Confirm that translation works by changing language in QGIS -> Settings -> Options (remeber to reload the plugin first)
In OSWGEO4 Shell
C:\OSGeo4W>pylupdate5.exe -verbose "C:\Users\SEVPLI\Documents\projekt\urdar\gitclone\IntrasisDBManager\intrasis_db_mgr\i18n\IntrasisDBManager.pro"
C:\OSGeo4W>linguist
C:\OSGeo4W>cd C:\standalone\QtLinguist-Standalone-5.12.0\QtLinguist\bin
C:\standalone\QtLinguist-Standalone-5.12.0\QtLinguist\bin>lrelease.exe "C:\Users\SEVPLI\Documents\projekt\urdar\gitclone\IntrasisDBManager\intrasis_db_mgr\i18n\intrasis_db_mgr_sv.ts"
Updating 'C:\Users\SEVPLI\Documents\projekt\urdar\gitclone\IntrasisDBManager\intrasis_db_mgr\i18n\intrasis_db_mgr_sv.qm'...
Generated 131 translation(s) (131 finished and 0 unfinished)
Ignored 12 untranslated source text(s)
C:\standalone\QtLinguist-Standalone-5.12.0\QtLinguist\bin>lrelease.exe "C:\Users\SEVPLI\Documents\projekt\urdar\gitclone\IntrasisDBManager\intrasis_db_mgr\i18n\intrasis_db_mgr_en_US.ts"
Updating 'C:\Users\SEVPLI\Documents\projekt\urdar\gitclone\IntrasisDBManager\intrasis_db_mgr\i18n\intrasis_db_mgr_en_US.qm'...
Generated 131 translation(s) (131 finished and 0 unfinished)
Ignored 12 untranslated source text(s)This section describes how to recreate a local Intrasis Database using Postgres server. For details on Postgres please refer to Postgres documentation. Windows CMD was used to run the commands.
REM Set the postgres password as a temporary environment variable. Only used for testing!
set “PGPASSWORD=postgres”
REM Create the database “intrasistest01”
createdb -h localhost -p 5432 -U postgres intrasistest01
REM Restore the database with u20043.backup
pg_restore.exe -h localhost -p 5432 -U postgres -d intrasistest01 -v -O -x --no-security-labels “C:\db_backups\u20043.backup”
REM set owner and enable Extensions
psql -U postgres -d intrasistest01 -c “ALTER DATABASE intrasistest01 OWNER TO intrasis_second”;
psql -U postgres -d intrasistest01 -c “CREATE EXTENSION IF NOT EXISTS dblink”;
psql -U postgres -d intrasistest01 -c “CREATE EXTENSION IF NOT EXISTS postgis”;
psql -U postgres -d intrasistest01 -c “CREATE EXTENSION IF NOT EXISTS postgis_raster”;REM Script to create intrasis databases for testing QGIS intrasis plugin
REM Use at your own risk! Use only in test environment! Not on a "real" server
REM set the password to postgresql server/database do not set password in a real environment
set "PGPASSWORD=lösenord"
REM for loop ([start], [step], [end] example create 100 databases (1, 1, 100)
for /L %%i in (1,1,100) do (
REM print current iteration
echo intrasistwo_test_db%%i
REM skapa databas createdb -h host -p port (standard är 5432) -U är databasanvändaren
"C:\Program Files\PostgreSQL\15\bin\createdb" -h localhost -p 5432 -U USERNAME intrasistwo_test_db%%i
REM set owner to your "intrasisuser"
"C:\Program Files\PostgreSQL\15\bin\psql" -U SEVPLI -p 5432 -d intrasistwo_test_db%%i -c "ALTER DATABASE intrasistwo_test_db%%i OWNER TO intrasisother";
REM create dblink and postgis extensions
"C:\Program Files\PostgreSQL\15\bin\psql" -U SEVPLI -p 5432 -d intrasistwo_test_db%%i -c "CREATE EXTENSION IF NOT EXISTS dblink";
"C:\Program Files\PostgreSQL\15\bin\psql" -U SEVPLI -p 5432 -d intrasistwo_test_db%%i -c "CREATE EXTENSION IF NOT EXISTS postgis";
"C:\Program Files\PostgreSQL\15\bin\psql" -U SEVPLI -p 5432 -d intrasistwo_test_db%%i -c "CREATE EXTENSION IF NOT EXISTS postgis_raster";
REM Do the restore
"C:\Program Files\PostgreSQL\15\bin\pg_restore.exe" -h localhost -p 5432 -U SEVPLI -d intrasistwo_test_db%%i -v -O -x --no-security-labels "C:\Users\SEVPLI\Downloads\db_backups\db_backups\u20043.backup"
)