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:

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:

Link HotReload in CMakeLists.txt (adapt to match your installed Felgo Hot Reload client path, the Qt version, and the compiler in use):

# Felgo Hot Reload for host builds
set(FELGO_HOT_RELOAD_PATH "../client/${QT_VERSION}/macos")

set(CMAKE_PREFIX_PATH "${FELGO_HOT_RELOAD_PATH};${CMAKE_PREFIX_PATH}")

# Felgo Hot Reload for cross-compiling

# list(APPEND CMAKE_FIND_ROOT_PATH "../client/${QT_VERSION}/gcc_64")

find_package(FelgoHotReload CONFIG REQUIRED)

# Link Felgo Hot Reload

felgohotreload_configure_executable(${CURRENT_PROJECT_NAME})

There are some special requirements when adding Felgo Hot Reload to an Android project using CMake:

Because of this CMake bug, FelgoHotReload package is not found by updating the CMAKE_PREFIX_PATH variable. Instead, set the FelgoHotReload_DIR variable to the directory containing the desired FelgoHotReload package config files. For example, ../client/6.6.1/android_armv7/lib/cmake/FelgoHotReload
felgohotreload_configure_executable(target) must be called before qt_finalize_target(target)

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):

# Add Felgo Hot Reload

FELGO_HOT_RELOAD_PATH = "../client/$${QT_VERSION}/macos"

include("$${FELGO_HOT_RELOAD_PATH}/qmake/FelgoHotReload.pri")

3.2.2. Load Hot Reload instead of your main QML file

It makes sense to bundle Felgo Hot Reload only for the application's debug build. This way, you’ll have a debug build with Felgo Hot Reload for lightning-fast development and testing and your typical release build for publishing.

It is good practice at Felgo to have a mechanism for easily enabling or disabling Felgo Hot Reload. That’s why when Felgo Hot Reloaded is added to a project, it defines the USE_FELGO_HOT_RELOAD symbol. You can use it inside your C++ code to add Felgo Hot Reload specific code. The Demo Project shows how this is done.

If you are tweaking your project manually, you need to load the Felgo Hot Reload component instead of the main QML file in your application logic. To do it, you need to:

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);

3.2.3. Felgo Hot Reload Configuration File

Apply the following changes to your project:

You have to create a hot_reload_config.json file in the project root directory. It’s a JSON configuration file that defines which paths to reload. It must define the following properties:

main_qml_file

A string containing the relative path to the main QML file that will be loaded as the root element.
If the main QML file is located outside the project’s directory tree, it is recommended that you put the main QML’s directory into the qml_module_paths list.
The main_qml_file should be relative to the project directory
Alternatively for backwards compatibility (pre 1.3.0) main_qml_file can be relative to any of the included qml_module_paths

qml_module_paths

List of paths to QML modules that should be reloaded. It is best to have the QML sources in a folder structure that reflects the plugin import URI.
You can add paths either as a string containing the source directory which contains the module’s QML files
Or as JSON objects containing two keys:

path: it contains the source directory of the module’s QML files
target_path: if set, the files from the module will be stored in the cache under that relative path. If the path is associated with a module that’s imported using the module URI, the target_path and module URI must match

For example, the object {"path": "qml/module", "target_path": "my/application/module"} will result in copying the QML files under source path qml/module under my/application/module cache path.
If this property is skipped, the default files from the current project configuration are used. You can use relative or absolute paths. The default value is a list containing only “this” folder: ["."]

qml_plugin_paths

List of paths to QML module binaries that should be loaded. It is used only if use_local_plugins is true. You can use relative or absolute paths. The default value is an empty list: []
You can add paths either as a relative or absolute path string to the plugin directory (example ["./myModule", "/home/user/modules"]
Or as a JSON object with following keys:

path (required): it contains the directory where the module binaries are located
target_path (optional): must be set for modules that are imported in QML by their import URI. The import URI and the target path must match. eg. if a QML module has the import URI "My.Qml.Module", use a target_path of My/Qml/Module
platform (optional): the binaries located under path are to be used for the specified platform. List of possible platforms: windows, linux, macos, osx, android, ios, qnx or any other value returned by QSysInfo::productType() or QSysInfo::kernelType(). If not set, the binaries will be used for all platforms..
compiler (optional): the binaries located under path are to be used for the specified compiler. 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. If not set, the binaries will be used with any compiler..
qt_version (optional): the binaries located under path are to be used for the specified Qt version. The version is specified in MAJOR.MINOR.PATCH string format. If not set, the binaries will be used with any Qt version.

For example: [{"path": "./myModule", "platform": "linux", "compiler": "gcc_64", "qt_version": "6.5.3"}] path will be copied only for a client on a linux platform compiled under gcc_64 and linked against Qt 6.5.3 libraries.

use_local_plugins

The bool variable determines whether to use QML module binaries from the paths given by qml_plugin_paths. If set to false, Felgo Hot Reload will copy the libraries to a cache location, which decreases performance.

Here is an example of a valid hot_reload_config.json file:

{

"main_qml_file": "qml/main.qml",

"qml_module_paths": ["qml"],

"qml_plugin_paths": ["."],

"use_local_plugins": true

}

And a more complex example, assuming in qml/module you have defined a module with import URI my.application.module:

{

"main_qml_file": "qml/main.qml",

"qml_module_paths": [

"qml",

{

"path": "qml/module",

"target_path": "my/application/module"

}

"qml_plugin_paths": [

{

"path": "build/x64_debug/my/application/module",

"target_path": "my/application/module",

"platform": "linux",

"compiler": "gcc_64",

"qt_version": "6.5.3"

}

"use_local_plugins": true

}

Note: For your convenience, a sample JSON configuration file is in the Demo Project repository (hot_reload_config.json). You may copy it and adapt it to your project.

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.1 (2024-10-02)

Improvements

Felgo Hot Reload has an improved first use flow. You are no longer required to enter the Settings page to enter the license key. Instead, you are prompted to enter it when you start the Felgo Hot Reload GUI application for the first time.
Filtering criteria for files monitored is further improved. Felgo Hot Reload uses an extended list of generated files and directories that will not be transferred to client applications. Also the paths in qml_module_paths and qml_plugin_paths configuration keys are no longer filtered out.
Felgo Hot Reload occupies less disk space on your Windows and Linux development machine after we removed several Qt components dependencies.

Fixes

Reports errors when adding a duplicate property or function inside a component
Fixes various issues when changing the QML tree
Fixes issues when returning properties to their default values
Fixes issues when editing PropertyChanges objects
Fixes a crash when adding a function

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

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