This page explains the process of updating the project to target a newer Qt 6 version (such as Qt 6.8 to 6.9). This may be desirable sometimes to obtain new features for example. Updating to a new major version of Qt (such as Qt 6 to 7) will likely involve a LOT more work and will probably not be necessary over the lifetime of the project, so that will not be described here.

Also, if you are going to go through the process of updating Qt for the project, make sure you follow ALL of the steps laid out in this page, IN ORDER.

(1) Updating Your Qt Development Environment

IMPORTANT: Before proceeding through this section, ensure that you have no build errors on your current branch. This is important so that later if the update causes any issues you know that they are only due to the update.

To update the program you must first update the Qt installation on your machine. To do this, open the Qt Maintenance Tool (Open Qt Creator->Tools->Qt Maintenance Tool->Start Maintenance Tool).

Log in to your account if asked. Then, select "Add or remove components" when prompted on what you would like to do.

You will now be shown a list of the Qt versions available for install/removal. Select the version of Qt 6 you would like to install and choose the appropriate libraries described in Installing Qt. The example below is upgrading to 6.9.0 from 6.8.2.

NOTE: Optionally, you can also remove the older version(s) of Qt here.

Then proceed through the installer.

After the install has completed, restart Qt Creator and reopen the project. You now need to verify that Qt Creator is using the correct Qt version to build the project. To do this, open the Projects tab on the side pane. On the left hand side of this screen there should be a section called Build & Run with a list of Qt versions. Select the version you just installed (if it isn't already selected).

Now click the computer monitor icon in the bottom left and once again click the Qt version that you just installed.

Now you can attempt to build the project.

(2) Fixing Errors

Changes in the libraries between Qt versions may introduce breakages in the code. For instance, updating to Qt 6.9 caused these errors due to a change in how the constructor works for QString:

This was fixed by explicitly casting the PieceTypes to a char.

When fixing errors caused by updates, make sure you do this for all branches!

(3) Finalizing the Update

You must now change the Qt version that the automatic build system uses when building the project (for more information on the automatic build system see GitHub Actions Automatic Builds). To do this, first ensure you are on the master branch and open up the workflow file at /.github/workflows/autobuild-linux.yml (also you can click here).

Then, edit the version: entry in the Set up Qt environment section so that it reflects the new version and commit the changes.

Next, create a new release with the updated Qt version. To do this, once again see GitHub Actions Automatic Builds. Ensure that the build was successful by checking the Actions tab.

Finally, update the README.md file on the master branch to reflect the new Qt version.

(4) Updating Qt On the Kiosk Machine

Doing this step immediately after the update is optional, but if you don't do it immediately after updating the target version you will need to do it next time there is a "real" feature update for the display.

Updating Qt on the kiosk follows the same process as described in (1) Updating Your Qt Development Environment (you must use Desktop mode on the kiosk, see General Usage Details).

After this, update the program on the kiosk using the instructions in General Usage Details.