Company Confidential
Table of Contents:
1.1. Felgo Hot Reload GUI Application 2
1.2. Felgo Hot Reload Library 2
3.2. Initial Project Configuration 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.1. Start and connect Felgo Hot Reload 13
4.2. Auto-start Felgo Hot Reload 15
4.4. Development Instructions 17
4.5. GUI application options 17
7.1. The developed application window is not set on top on Linux systems 19
7.3. Removing layer.effects with Qt 6.4.1 makes the parent item invisible 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
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:
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.
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.
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.
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.
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.
Here, we cover the two most common build systems: CMake and qmake (Qt 5.15).
Apply the following changes to configure your CMake-based project with Felgo Hot Reload:
# Felgo Hot Reload for host builds 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.
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") |
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") |
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.
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); |
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.
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" |
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" } ] |
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:
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:
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" },
] |
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" } ] |
Note: When the Felgo Hot Reload GUI application first starts on Windows, it may ask for firewall permission. Make sure to allow access.
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.
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.
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.
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.
There are several actions and configuration options available for the Felgo Hot Reload GUI application.
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.
In both cases, make sure you use the client libraries and Felgo Hot Reload GUI app from the same version.
You can access the complete changelog here
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:
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
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.
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:
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
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
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.
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.
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