Felgo Hot Reload Guide

Table of Contents:

1. Overview        2

1.1. Felgo Hot Reload GUI Application        2

1.2. Felgo Hot Reload Library        2

2. Installation        3

3. Preparation and Setup        4

3.1. License Key        4

3.2. Initial Project Configuration        6

3.2.1. Build System        6

3.2.2. Load Hot Reload instead of your main QML file        7

3.2.3 Update C++ initialization code        8

3.2.4. Create Felgo Hot Reload Configuration File        8

3.2.5. Advanced configuration topics        11

4. Usage        13

4.1. Start and connect Felgo Hot Reload        13

4.2. Auto-start Felgo Hot Reload        15

4.3. Load from Cache        16

4.4. Development Instructions        17

Restarts        17

Development        17

4.5. GUI application options        17

5. Demo Project        18

6. Changelog        18

Version 1.4.3 (2025-01-23)        18

Highlights        18

Fixes        19

Previous versions        19

7. Known issues        19

7.1. The developed application window is not set on top on Linux systems        19

7.2. Adding Felgo Hot Reload to a Qt6, gcc_64 project on Linux machines can make the CMake configuration fail        20

7.3. Removing layer.effects with Qt 6.4.1 makes the parent item invisible        20

7.4. Using a main_qml_file outside project directory may throw errors when using QML  imports with relative paths        20

7.5. Can’t get rid of the error screen when fixing an error        21

7.6. Issues when typing Connection ID on some Android device models when using Qt 6.7        21

7.7. Updating font assets in Qt < 6.4.0        22

7.8. Application does not find QML files starting with lowercase        22

8. Contact        22

1. Overview

Felgo Hot Reload empowers you to make instant QML and JS code changes and resource updates without recompilation or redeployment; it applies these changes without losing the state of your running application. If you are currently working on a sub-screen, you will not have to navigate to it again after every change, and you will stay exactly where you are in your application.

Felgo Hot Reload consists of two components:

• Felgo Hot Reload GUI application and
• Felgo Hot Reload library.

1.1. Felgo Hot Reload GUI Application

The Felgo Hot Reload GUI application (FelgoHotReload.exe on Windows or FelgoHotReload on other platforms) listens for project file changes and sends those changes to the running application. It is located in the root folder of the installation directory.

1.2. Felgo Hot Reload Library

The Felgo Hot Reload library. It gets linked into your application binary during the development workflow (not linked to the release version). You can integrate the library via qmake or CMake build system helpers. You can find the library in the client subfolder of the installation directory.

2. Installation

You can install Felgo Hot Reload using the specific installer for your development platform:

• Linux: https://install.felgo.com/fhr/FelgoHotReloadInstaller.run
• Windows: https://install.felgo.com/fhr/FelgoHotReloadInstaller.exe
• macOS: https://install.felgo.com/fhr/FelgoHotReloadInstaller.dmg

After downloading and starting the installer, you are asked to select:

•  The installation folder

• The Qt versions for which to install the Felgo Hot Reload library. You can select as many versions as you need. The Felgo Hot Reload GUI Application will be installed by default.

• Windows only: Start Menu Shortcuts

After the installation, you can start configuring your project to use Felgo Hot Reload.

3. Preparation and Setup

3.1. License Key

Before starting work, you need to provide a license key that you have retrieved from Felgo as a part of an order.

Open the Felgo Hot Reload GUI application. First, it will ask you to enter the license key. Enter the received license key and press “CONTINUE”.

If the given license key is valid, it will ask you to select a project directory. This step is necessary only once.

You have the option to skip this step by pressing “SKIP”. After selecting this option, the application will ask you to select a project directory. After choosing the directory, you will see a message that the license key is not set. Open the settings window from the banner or via the “Settings” button in the bottom left corner.

Locate the text field “License Key” at the very top of the screen.

Paste the received license key, and press “Save”.

When you successfully add a license, the License Banner will disappear. You will see information about your current license in the Felgo Hot Reload settings.

Note: If you have any questions or queries regarding obtaining or using a license key, please contact support@felgo.com.

3.2. Initial Project Configuration

In this section we give step-by-step instructions about how to integrate Felgo Hot Reload in a project. You can check the FelgoHotReloadDemo project to see all changes required for Felgo Hot Reload integration.

3.2.1. Build System

Here, we cover the two most common build systems: CMake and qmake (Qt 5.15).

CMake

Apply the following changes to configure your CMake-based project with Felgo Hot Reload:

• Add the FelgoHotReload CMake package in CMakeLists.txt (adapt to match your installed Felgo Hot Reload client path, the Qt version, and the compiler in use):

Note: Make sure to call felgohotreload_configure_executable(target) before qt_finalize_target(target) when adding Felgo Hot Reload to a Qt 6 Android project using CMake.

qmake

Note: qmake support is only maintained for Qt 5.15.

Apply the following changes to configure your qmake-based project with Felgo Hot Reload:

• Include and link FelgoHotReload in the qmake .pro file (adapt to match your installed Felgo Hot Reload client path, Qt version, and the compiler in use):

qmake

Note: qmake support is only available for Qt 5.15.

Apply the following changes to configure your qmake-based project with Felgo Hot Reload:

• Include and link HotReload in the qmake pro file (adapt to match your installed Felgo Hot Reload client path, Qt version, and the compiler in use):

3.2.2. Load Hot Reload instead of your main QML file

Typically, you only include Felgo Hot Reload in the application's debug build. This approach allows for a debug build with Felgo Hot Reload for development and testing while maintaining a separate release build for distribution.

It's advisable to have a method that allows you to toggle Felgo Hot Reload on and off quickly. When you incorporate Felgo Hot Reload into a project, it automatically defines the USE_FELGO_HOT_RELOAD symbol. This symbol can be utilized in your C++ code to write Felgo Hot Reload-specific instructions.

The following steps are required to load the Felgo Hot Reload instead of the main QML file in your application logic:

• Include the Felgo Hot Reload header file:

• #include <FelgoHotReload>

• Comment out the loading of the main QML file:

• // qmlEngine.load(mainQmlFile);

• Load FelgoHotReload instead, e.g., with static initialization:

• static FelgoHotReload felgoHotReload(&qmlEngine);

Note: The Demo Project illustrates implementing this with the conditional USE_FELGO_HOT_RELOAD symbol.

3.2.3 Update C++ initialization code

Making the changes above will delay loading the QML file until you’ve connected your application to the Felgo Hot Reload GUI application. Because of this, any calls to QQmlApplicationEngine::rootObjects() will return an empty list. If you need to do some initialization steps that rely on these objects, we recommend using a handler for the QQmlApplicationEngine::objectCreated() signal. Move your initialization code inside the handler to be sure the object you require is created.

For example, the following code:

is updated to:

3.2.4. Create Felgo Hot Reload Configuration File

Felgo Hot Reload needs information about your project structure. It will watch specified files for changes and apply them to the running application. The information is stored inside a configuration file named hot_reload_config.json. Create this file inside your project's root directory.

Note: This step is not required if all application QML files are in the same directory and you don’t use QML modules in your project.

As an example, a project defining three modules with URIs DemoStaticPlugin , Demo.SharedPlugin and demo.qml.module will have a configuration JSON similar to this:

Note: You can build the Demo Project repository to obtain a sample JSON configuration file. You may copy it and adapt it to your project.

The following sections provide details about the file contents.

3.2.4.1. Root QML file

This is the first QML file loaded by your application. It is the parameter of the  QQmlEngine::load, QQmlEngine::loadFromModule, or QQuickView constructor call. The path must be relative to the configuration JSON and added to the main_qml_file JSON key.

It will look something like:

3.2.4.2. Paths to defined QML modules and plugins

Felgo Hot Reload can reload files added to Qt modules or plugins if you specify:

• The path to the module or plugin source files
• The path to the  built module or plugin libraries and qmldir file

To add the path to the module or plugin sources:

• If not already present in the configuration JSON, add the qml_module_paths key. It contains an array.

• Add a new object in the qml_module_paths array. The object has the following keys and their associated values:

• path: Add the directory path where the CMakeLists.txt file defines the module or plugin. It must be relative to the configuration JSON file.
• target_path: Here, set a path obtained from the module URI by replacing the dots with slashes. For example, for a module with URI Demo.SharedPlugin should be set to Demo/SharedPlugin

To add the path to module or plugin libraries and qmldir file:

• If not already present in the configuration JSON, add the qml_plugin_paths key. It contains an array.
• Add a new object in the qml_plugin_paths array. The new object has the following keys and associated values:

• path: Here, add the path to the folder where the generated qmldir file for this module or plugin is. This path is inside your project’s build directory and must be relative to the configuration JSON file.
• target_path: Add a path obtained from the module URI here by replacing the dots with slashes. For example, a module with URI Demo.SharedPlugin should be set to Demo/SharedPlugin. Usually is the same path as the one added for the sources directory.

A full Felgo Hot Reload configuration for a module looks similar to the following:

3.2.4.3. Paths to other directories containing QML files or other resources

Felgo Hot Reload can reload files not added to any Qt module or plugin. In this case, you have to specify only the path to the source directory:

• If not already present in the configuration JSON, add the qml_module_paths key. It contains an array.

• Add a new object in the qml_module_paths array. The object has the following keys and their associated values:

• path: Add the path to the directory where the files are. It must be relative to the configuration JSON file.
• target_path: add the path where the Qt Resource system expects to find these files. Depending on your configuration, it is one of the following:

• The source path directory name when files are not added to the Qt resource system. Note: In this case, you may replace the entire JSON object with the string associated with the path key. For example: “qml_module_paths”: [“qml”] 
• The Qt resource system path for the files. This can be one of the following:

• the prefix used inside the project's .qrc file
• the prefix specified with qt_add_resources CMake function

3.2.4.4. Information about loading module and plugin binaries

Felgo Hot Reload creates a local copy of the configured module and plugin libraries. Copying can be unnecessarily time-consuming when running the application locally on your development machine. You can override the behavior with the use_local_plugins key inside the configuration file:

• If it's set to true, Felgo Hot Reload will not create the local copy of the libraries. It will use the libraries inside the paths from the  qml_plugin_paths array.
• If set to false, Felgo Hot Reload will make a local copy of the libraries.

3.2.5. Advanced configuration topics

3.2.5.1. Configuring multi-platform projects

Plugin library paths depend on the platform, compiler, and Qt version used. Felgo Hot Reload allows you to specify which configuration to use for a specific path. The objects inside the qml_plugin_paths array support several optional keys:

• compiler: Specify which compiler should use this plugin path. List of possible compilers: gcc_64, android, android_arm64_v8a, android_arm7, android_x86, android_x86_64, clang_64, macos, ios, mingw81_64, mingw_64, msvc2019_64, msvc2022_x64. If not set, Felgo Hot Reload will use the libraries for all compilers.
• qt_version: Specify which Qt version should use this plugin path. The version is using the MAJOR.MINOR.PATCH string format. If not set, Felgo Hot Reload will use the libraries for all Qt versions.

The configuration for a module used on Linux and Windows development can look like this:

3.2.5.2. Configuring projects with resource aliases

Felgo Hot Reload supports reloading files using a resource alias. Add an entry inside the qml_module_paths array for the resources:

• path: Add here the path to the directory where the files are. It must be relative to the configuration JSON file.
• target_path: The key must be set to the resource alias directory.

For example, if you add resources using the following CMake command:

The configuration looks as follows:

4. Usage

4.1. Start and connect Felgo Hot Reload

• Double-click the FelgoHotReload executable.
• This opens a file selection dialog. Select the path to your project’s QML source folder or the folder containing the hot_reload_config.json file (depending on whether you use the QML module support).

• Alternatively, you can start it from the command line by providing the path as an argument, e.g., FelgoHotReload <project-path>, or create a shortcut appending the path to the application executable.

Note: When the Felgo Hot Reload GUI application first starts on Windows, it may ask for firewall permission. Make sure to allow access.

• Start your project configured as mentioned above (with the linked FelgoHotReload library).

• A connection dialog pops up.

• Select Connect to Local for local development (only available on Desktop platforms).
• Enter the Connection ID that is shown in the bottom left corner of the Felgo Hot Reload GUI application and press Connect to Remote to connect as a device to a remote GUI application (use case for on-device testing to connect a device to the local development PC).

• Accept the connection request on the Felgo Hot Reload GUI application.
• Wait until the project is loaded, and you will be ready.

4.2. Auto-start Felgo Hot Reload

You can automatically start up a connection or start the application from cached files with the following methods:

• By setting the environment variable FHR_AUTO_START=<value>

• By passing a command line argument --autostart <value>

• Note that setting a command line argument will override the checks for the environment variable, even if the argument is invalid!

The value set for either the environment variable or the command line argument can be the following:

• local - Will start a local connection to the server, similarly by pressing the Connect to Local button
• cache - Will start the cached version of the application if possible
• none - Will not do any auto-start and start up normally.

• Use it if the FHR_AUTO_START environment variable is set, but we want to bypass it with the command line argument --autostart none.

• <ConnectionID> - Will start a remote connection to the GUI application’s Connection ID specified by <ConnectionID>

• <ConnectionID> is a 8 or 12-character ID, without space separating the numbers
• For example: --autostart 123456789ABC to automatically connect to a GUI application with the following Connection ID: 1234 5678 9ABC

If the application is not started automatically with the given parameters, the default starting screen will appear, with an error message describing why the auto start was unsuccessful.

4.3. Load from Cache

You can start your application without access to the Felgo Hot Reload GUI application. This option is available only if the project has been loaded at least once without QML errors. To do this, select the “Load from Cache” option.

This will start your application with the latest error-free configuration and without Felgo Hot Reload functionality.

4.4. Development Instructions

Restarts

You can restart your project application anytime. The Hot Reload GUI application does not need to be restarted and can remain open in the background.

Exception: If you change the JSON configuration, you need to restart the Felgo Hot Reload GUI application.

Development

Make changes in your code and save the file. The changes are applied in the running application. If errors in your code occur or Hot Reload cannot be applied, you see an error overlay with a description.

Exception: You make changes to files bundled within executable and used via absolute paths. Example: import qrc:/MyModule as MyModule will use the files from the QRC system and not the development files.

4.5. GUI application options

There are several actions and configuration options available for the Felgo Hot Reload GUI application.

• Disconnect
  Use this action when you want to disconnect from the connected client. The application either shows the connection screen again or quits, depending on the “Full Reload” availability.
• Clear Log
  Use this action when you want to clear the log window.
• Full Reload
  Use this action when you want the connected client to reload all QML files and reset to its initial application state. Note: This is only visible if the option is supported with the current license key.
• Stay on Top
  Enable this option to keep the developed application window on top. It has effect only on platforms that support multiple windows.
• Logs
  Enable this option if you want the Felgo Hot Reload GUI app to capture and display developed application logs.
• Auto Clear
  Enable this option to clear the log windows before every hot reload update.
• Hot Reload
  Enable this option to have the hot reload feature active. If disabled, a full reload is performed after every code change. Note: This is only visible if the option is supported with the current license key.
• Clear Cache
  Use this action to clear the cache for the loaded project.
• Remove
  Use this action to remove the selected client from the Felgo Hot Reload GUI application.

5. Demo Project

You can also access the demo project via GitHub: https://github.com/FelgoSDK/FelgoHotReloadDemo.

The project demonstrates how to add Felgo Hot Reload to an existing project. To run the project, follow the instructions in the README file.

6. Changelog

Version 1.4.3 (2025-01-23)

Highlights

• We further reduced the Felgo Hot Reload dependencies. It no longer depends on the Qt Websockets module. This change breaks compatibility to older versions. If you try and use the client library and the Felgo Hot Reload GUI app from different versions:

• you will see a relevant error message when using Connect to Local
• you will see a generic time-out issue when using Connect to Remote

In both cases, make sure you use the client libraries and Felgo Hot Reload GUI app from the same version.

Fixes

• iOS libraries contain the x86 simulator architecture
• Fixes issues where removing an active animation leaves items in inconsistent states.
• Fixes issues when parsing QML expressions
• Fixes issues with the components used when re-activating a Loader.
• Fixes issues of Felgo Hot Reload GUI app network configuration.

Previous versions

You can access the complete changelog here

7. Known issues

7.1. The developed application window is not set on top on Linux systems

Description

On Linux systems, the developed application window is not always set on top compared to Windows and macOS systems. This causes the application window to end up behind other windows, in particular use cases.

Workaround

Use the “Always on top” feature of Linux:

• Right-click the application window
• Select “Always on Top”

7.2. Adding Felgo Hot Reload to a Qt6, gcc_64 project on Linux machines can make the CMake configuration fail

Description

A CMake error stating that the XKB::XKB target has not been found

Workaround

Install libxkbcommon-dev package: sudo apt-get install libxkbcommon-dev

7.3. Removing layer.effects with Qt 6.4.1 makes the parent item invisible

Description

Because of a bug in Qt (https://bugreports.qt.io/browse/QTBUG-109506) for Qt 6.4.1, removing the layer.effect from a QML item makes that item invisible.

Workaround

A workaround to prevent an invisible item is to set the layer.enabled to false as well. This bug was fixed with Qt 6.4.3.

7.4. Using a main_qml_file outside project directory may throw errors when using QML  imports with relative paths

Description

Because of how we handle the main_qml_file outside the project directory, relative paths for QML imports may become invalid.

Workaround

Update the import QML relative paths:

• Start relative imports with “../”. This will point to the parent directory of the paths defined in qml_module_paths
• Build your relative import path from there

7.5. Can’t get rid of the error screen when fixing an error

Description

In some cases. If you fix an QML issue that triggered the Felgo Hot Reload error screen in a different way than reverting  the change that caused it, the error is still reported and error screen shown. For example, consider the following component definition:

If you remove the componentColor property, Felgo Hot Reload will show the error screen. You can fix the issue in 2 ways:

• Undo your change and add back the componentColor property inside the rectangle
• Add the componentColor property in the component root Item

If you choose the second option, the error screen will not disappear.

Workaround

• Fix the error by reverting the changes that caused it, or
• Full reload your application after fixing the error

7.6. Issues when typing Connection ID on some Android device models when using Qt 6.7

Description

More characters than typed are added when typing the Connection ID on some Android device models. It’s caused by this known Qt issue: https://doc.qt.io/qt-6/android-platform-notes.html#predictive-text in combination with QTBUG-125410

Workaround

• Use the Auto-Start Felgo Hot Reload feature, or
• Copy and paste the entire Connection ID at once

7.7. Updating font assets in Qt < 6.4.0

Description

No change is observed after removing or updating a font file (eg. .ttf) loaded by a QML FontLoader when using Qt versions before 6.4.0. This is a limitation imposed by the Qt API.

Workaround

Restart your application.

7.8. Application does not find QML files starting with lowercase

Description

Your application reports that it did not find a QML file starting with a lowercase letter.

Workaround

QML files starting with lowercase letters do not adhere to Qt recommendations: https://doc.qt.io/qt-6/qtqml-documents-definetypes.html. Rename your QML file to start with an uppercase letter and update your code accordingly.

8. Contact

If you have any questions, please check the Felgo Hot Reload FAQ page.

If you haven’t found an answer to your question or want to reach us, please do it via the FELGO support inbox:
support@felgo.com