Published using Google Docs
Felgo Hot Reload Guide
Updated automatically every 5 minutes

Company Confidential

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:

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:

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:

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

set(FelgoHotReload_DIR "${FELGO_HOT_RELOAD_PATH}/lib/cmake/FelgoHotReload CACHE PATH “FelgoHotReload directory” FORCE)

# 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})

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:

# Add Felgo Hot Reload

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

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

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:

# 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

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:

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:

qmlEngine.load(mainQmlFile);

initializeApplication(qmlEngine.rootObjects().first());


is updated to:

//qmlEngine.load(mainQmlFile);

QObject::connect(&qmlEngine, &QQmlApplicationEngine::objectCreated, [&](QObject *object, const QUrl &url) {

  // You should check that the object is the one you are expecting

  initializeApplication(object);

});

static FelgoHotReload felgoHotReload(&qmlEngine);

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:

{

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

  "qml_module_paths":[

    "qml",

    {

      "path": "qml_static_plugin",

      "target_path": "DemoStaticPlugin"

    },

    {

      "path": "qml_shared_plugin",

      "target_path": "Demo/SharedPlugin"

    },

    {

      "path": "qml_module",

      "target_path": "demo/qml/module/qml_module"

    }

  ],

  "qml_plugin_paths":[

    {

      "path": "build/MSVC2019_64bit-Debug/DemoStaticPlugin",

      "target_path": "DemoStaticPlugin"

    },

    {

      "path": "build/MSVC2019_64bit-Debug/Demo/SharedPlugin",

      "target_path": "Demo/SharedPlugin"

    },

    {

      "path": "build/MSVC2019_64bit-Debug/demo/qml/module",

      "target_path": "demo/qml/module"

    }

  ],

  "use_local_plugins": true

}

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:

"main_qml_file": "qml/main.qml"

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:

To add the path to the module or plugin sources:

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

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

"qml_module_paths":[

  {

    "path": "qml_shared_plugin",

    "target_path": "Demo/SharedPlugin"

  }

],

"qml_plugin_paths":[

  {

    "path": "build/MSVC2019_64bit-Debug/Demo/SharedPlugin",

    "target_path": "Demo/SharedPlugin"

  }

]

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:

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:

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:

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

"qml_module_paths":[

  {

    "path": "qml_shared_plugin",

    "target_path": "Demo/SharedPlugin"

  }

],

"qml_plugin_paths":[

  {

    "path": "build/gcc_64bit-Debug/Demo/SharedPlugin",

    "target_path":" Demo/SharedPlugin",

    "compiler": "gcc_64",

    "qt_version": "6.5.3"

  },

  {

    "path": "build/MSVC2019_64bit-Debug/Demo/SharedPlugin",

    "target_path": "Demo/SharedPlugin",

    "compiler": "msvc2019_64",

    "qt_version": "6.4.1"

  },

 

]

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:

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

qt_add_resources(${PROJECT_NAME} "qml_files"

  PREFIX "qml/application_logic"

  # ${QML_FILES} is a list containing the QML files from the "qml" directory

  FILES ${QML_FILES}

)


The configuration looks as follows:

"qml_module_paths": [

  {

    "path": "qml",

    "target_path": "qml/application_logic"

  }

]

4. Usage

4.1. Start and connect Felgo Hot Reload

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

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:

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

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.

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

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

Fixes

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:

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:

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:

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

Workaround

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

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

© FELGO GmbH