This blog is written by Hannes Winkler, originally posted on industrialflutter.com

Flutter works on many platforms: from Web and Mobile, to Desktop and Embedded. When it comes to embedded, however, support is still constrained by the CPU architecture used. In a previous blog post, we made Flutter & Dart work on ARMv6 as a Proof of Concept. Now, we’re going to look at something more modern: The RISC-V architecture is an upcoming, free, open-source CPU architecture, showing great potential specifically for embedded use-cases.

In cooperation with Cloud-V, we made it possible to run Flutter apps on RISC-V hardware. This involves a few parts: the largest one is RISC-V support in the Dart programming language. Dart has its own compiler backend, which compiles Dart code into architecture-specific native code. So naturally, it is the component that contains the most architecture-specific parts. Fortunately, adding a RISC-V backend to the Dart SDK was already done by the Dart team in 2022: https://dart-review.googlesource.com/c/sdk/+/217289

Additionally, changes to the Flutter Engine (specifically the build scripts) are required to enable building for RISC-V. Lastly, the part that brings it all together — and that actually allows building and running Apps on RISC-V devices — is the Flutter Tool. We are working on PRs for the official Flutter Tool & Engine, but in the meantime, that functionality can be used via flutterpi_tool.

Engine

First, the Flutter engine has to be built for RISC-V. Normally, this involves checking out the engine sources and then using the engines gn script to generate the build files.

As an example, building for a Linux ARM64 machine roughly looks like this:

$ gclient sync
...

$ pushd engine/src && ./flutter/tools/gn \
 --linux --linux-cpu arm64 \
 --runtime-mode release \
 --embedder-for-target --disable-desktop-embeddings \
 --no-enable-unittests --no-build-glfw-shell \
 --no-build-embedder-examples
Generating GN files in: out/linux_release_arm64
Generating compile_commands took 77ms
Done. Made 1178 targets from 345 files in 433ms

$ ninja -C out/linux_release_arm64

The gn script that is being invoked there doesn't actually do that much; it's just a convenience script that converts the given command-line arguments into a different form, a args.gn file. This is then used by the actual gn tool to generate the build files. So technically, it's not strictly necessary to modify it; it would also be possible to skip the gn script and craft a special args.gn file for RISC-V manually. In this case, we modified it to allow passing --linux-cpu riscv64, for development convenience.

Setting up RISC-V cross-compilation

Of course, if you now try running a build like that, you’ll undoubtedly run into errors. One of the first errors that’ll appear is that the build scripts try to use the wrong sysroot for building the RISC-V 64 binaries.

The reason for that can be found in the sysroot.gni^1, which is a gn "header". This header has the job of resolving the correct sysroot to be used for cross-compilation. By default, the Flutter build will download & use its own custom sysroot^2 from a Google storage bucket. For platforms like linux-armv7, which are also not officially supported by the Flutter build, it's enough to just manually invoke those scripts to download the required sysroot. For RISC-V, however, this unfortunately does not work because there's no RISC-V sysroot present that could be downloaded from the Google storage bucket.

There are multiple ways to go forward here. You could, for example, build your own custom sysroot and use that. That could be done on a native RISC-V machine, in a VM, or in a Docker container. However, there’s an easier way: installing a RISC-V gcc will also install a minimal RISC-V “sysroot” that can be used to build simple binaries. Fortunately, the Flutter engine intentionally doesn’t have a lot of shared library decencies, which is ideal because we are using a minimal sysroot that might not have them. This approach was attempted and proved to work well enough for our purposes.

In practice, that means compilation is done without an explicit sysroot and clang auto-selects the RISC-V libc headers.

--- a/engine/src/build/config/sysroot.gni
+++ b/engine/src/build/config/sysroot.gni
@@ -21,7 +21,16 @@ if (current_toolchain == default_toolchain && target_sysroot != "") {diff
   import("//build/config/android/config.gni")
   sysroot = rebase_path("$android_toolchain_root/sysroot", root_build_dir)
 } else if (is_linux && !is_chromeos) {
-  if (use_default_linux_sysroot && !is_fuchsia) {
+  # install-sysroot.py doesn't provide a RISC-V 64 sysroot, which means
+  # we can't provide a default sysroot.
+  # 
+  # If we make this fail here, when use_default_linux_sysroot == true and 
+  # current_cpu == "riscv64", the sysroot choosing for arm/arm64/x64
+  # will fail as well, so we wouldn't be able to cross-compile the gen_snapshots
+  # and build the libflutter_engine.so in one build anymore.
+  #
+  # Instead we just silently use no sysroot for riscv64 at all.
+  if (use_default_linux_sysroot && !is_fuchsia && current_cpu != "riscv64") {
     if (current_cpu == "x64") {
       sysroot =
           rebase_path("//build/linux/debian_sid_amd64-sysroot", root_build_dir)

One more thing we have to do is actually make the compiler target riscv64-linux-gnu. There's a specific gn file that does the compiler setup. The RISC-V target handling can just be added there:

--- a/engine/src/build/config/compiler/BUILD.gn
+++ b/engine/src/build/config/compiler/BUILD.gn
@@ -288,6 +288,11 @@ config("compiler") {
       if (arm_tune != "") {
         cflags += [ "-mtune=$arm_tune" ]
       }
+    } else if (current_cpu == "riscv64") {
+      assert(is_clang)
+
+      cflags += [ "--target=riscv64-linux-gnu" ]
+      ldflags += [ "--target=riscv64-linux-gnu" ]
     }
 
     if (!is_android) {

Dependency issues

Attempting to build the engine now will result in an error while resolving the freetype2 headers via pkg-config. However, as far as I can tell, the engine checks out & builds its own copy of freetype2, so it seems like this resolved dependency isn't actually used. Simply removing the offending code fixes the issue:

--- a/engine/src/build/config/linux/BUILD.gn
+++ b/engine/src/build/config/linux/BUILD.gn
@@ -27,9 +27,9 @@ config("fontconfig") {
   libs = [ "fontconfig" ]
 }
 
-pkg_config("freetype2") {
-  packages = [ "freetype2" ]
-}
+#pkg_config("freetype2") {
+#  packages = [ "freetype2" ]
+#}
 
 config("x11") {
   libs = [

Compatibility Fixes

In addition to that, some engine headers do architecture detection (using preprocessor defines), and RISC-V detection was added to them:

--- a/engine/src/flutter/assets/native_assets.cc
+++ b/engine/src/flutter/assets/native_assets.cc
@@ -17,6 +17,8 @@ namespace flutter {
 #define kTargetArchitectureName "ia32"
 #elif defined(FML_ARCH_CPU_X86_64)
 #define kTargetArchitectureName "x64"
+#elif defined(FML_ARCH_CPU_RISCV64)
+#define kTargetArchitectureName "riscv64"
 #else
 #error Target architecture detection failed.
 #endif

--- a/engine/src/flutter/fml/build_config.h
+++ b/engine/src/flutter/fml/build_config.h
@@ -96,6 +96,11 @@
 #elif defined(__pnacl__)
 #define FML_ARCH_CPU_32_BITS 1
 #define FML_ARCH_CPU_LITTLE_ENDIAN 1
+#elif defined(__riscv) && __riscv_xlen == 64 && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+#define FML_ARCH_CPU_RISCV_FAMILY 1
+#define FML_ARCH_CPU_RISCV64 1
+#define FML_ARCH_CPU_64_BITS 1
+#define FML_ARCH_CPU_LITTLE_ENDIAN 1
 #else
 #error Please add support for your architecture in flutter/fml/build_config.h
 #endif

--- a/engine/src/flutter/third_party/tonic/common/build_config.h
+++ b/engine/src/flutter/third_party/tonic/common/build_config.h
@@ -103,6 +103,11 @@
 #define ARCH_CPU_32_BITS 1
 #define ARCH_CPU_LITTLE_ENDIAN 1
 #endif
+#elif defined(__riscv) && __riscv_xlen == 64 && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+#define ARCH_CPU_RISCV_FAMILY 1
+#define ARCH_CPU_RISCV64 1
+#define ARCH_CPU_64_BITS 1
+#define ARCH_CPU_LITTLE_ENDIAN 1
 #else
 #error Please add support for your architecture in build/build_config.h
 #endif

Building the RISC-V Engine in CI

All those patches were then pushed to a custom CI pipeline at https://github.com/ardera/flutter-ci. This CI essentially watches for Flutter updates and builds the engine with the applied compatibility changes, for a lot of different architectures:

• It builds the Flutter engine for armv7, aarch64 & x64, with separate debug symbols, partially with CPU-specific tuning (for Pi 3 & 4)
• Furthermore, it builds the Dart cross compiler (gen_snapshot) for a lot of different host & target combinations, including linux (arm/arm64/x64/riscv64), windows & mac targeting all the different linux architectures.

The built artifacts for all the different architectures are then published as a GitHub release.

Running RISC-V Flutter Apps

Now that all the necessary artifacts are present, they can be used to assemble Flutter apps. Normally, this is done by the Flutter Tool, which downloads these artifacts from a Google Storage bucket maintained by the Flutter team. In this case, however, the modifications were made to flutterpi_tool.

In general, there was not much work involved here. Just recognizing riscv64 as a uname output for architecture detection and adding the correct values to some enumerations:
https://github.com/ardera/flutterpi_tool/commit/443c8efbfdf884701a1e097726b7a6039a0c19d5

Demonstration

KDAB used a Banana Pi BPI-F3, with free compute provided by Cloud-V. This platform helped us to get Flutter running on RISC-V. You can try it yourself and speed up your own software development by getting a free RISC-V compute from Cloud-V.

Contact:
Cloud V cloud-v@10xengineers.ai
KDAB https://www.kdab.com/contact/

Thanks to Cloud-V (a project by 10xEngineers) for demonstrating how to run Flutter on RISC-V hardware.

Bringing Flutter to RISC-V was originally published in Industrial Flutter on Medium, where people are continuing the conversation by highlighting and responding to this story.

Most desktop applications are single-instance, meaning that if the user attempts to open the application again, the existing instance is typically brought to the foreground instead of launching a new one.

Flutter applications do not behave like this out of the box for all desktop platforms. Desktop Linux and Windows require some extra work.

Section 1: Using packages

Using packages to achieve single-instance applications in Flutter is possible. Basic functionality to focus on an existing window when it is re-launched is supported. Using packages is a lot simpler than modifying platform-specific code generated by Flutter.

Recommended packages:

• unix_single_instance: Prevents multiple instances on Linux/macOS.
• windows_single_instance: A similar solution for Windows.
• window_manager: Provides control over window states like showing and focusing.

Example:

1. flutter pub add window_manager
2. flutter pub add windows_single_instance
3. flutter pub add unix_single_instance

void main(List<String> args) async {
 WidgetsFlutterBinding.ensureInitialized();
   // Initialize the window manager to control the app window
 await windowManager.ensureInitialized();

  // Enforce single-instance behavior based on the platform
 if (Platform.isLinux || Platform.isMacOS) {
   if (!await unixSingleInstance(args, _onSecondInstance)) exit(0);
 } else if (Platform.isWindows) {
   await WindowsSingleInstance.ensureSingleInstance(
    args,
    "custom_identifier",
    onSecondWindow: _onSecondInstance,
   );
 }

  runApp(const MyApp());
}

// Handle what happens when a second instance is launched
void _onSecondInstance(List<dynamic> decodedArgs) async {
  windowManager.waitUntilReadyToShow(null, () async {
    await windowManager.show();
    await windowManager.focus();
  });
}

Section 2: Manual implementation

You can achieve the same, and in some cases, more reliable results, by implementing single-instance enforcement in the files generated by Flutter. Doing it this way allows you much finer control over the behavior. It does have some downsides, as you need to maintain the code yourself.

Note:
It is possible to enforce single instances using Dart’s RandomAccessFile, as it provides a way to lock files. The first instance would lock a file, the second instance would check if the file is locked, and then not start.

Linux Desktop

Desktop Linux applications built with Flutter use the GTK framework under the hood. By default, a Flutter application on Linux may allow multiple instances to run simultaneously. To enforce single-instance behavior, you can make changes to the linux/my_application.cc file. Below are the steps and explanations for each modification.

Step 1: Remove the G_APPLICATION_NON_UNIQUE Flag

The G_APPLICATION_NON_UNIQUE flag in GTK allows multiple instances of an application to run. To enforce single-instance behavior, you need to remove this flag from the application initialization code.

MyApplication* my_application_new() {
  return MY_APPLICATION(
	g_object_new(
		my_application_get_type(), 
		"application-id", APPLICATION_ID,
		// "flags", G_APPLICATION_NON_UNIQUE,
    	nullptr)
	);
}

By removing the G_APPLICATION_NON_UNIQUE flag, the application becomes single-instance.

Step 2: Check for Existing Windows and Present Them

When the application is re-launched, the GApplication::activate signal is triggered. In this signal handler, you can check if a window is already open. If it exists, bring it to the foreground using the gtk_window_present() function. Otherwise, create a new window.

// Implements GApplication::activate.
static void my_application_activate(GApplication* application) {
    MyApplication* self = MY_APPLICATION(application);

    GList* list = gtk_application_get_windows(
GTK_APPLICATION(application));

    GtkWindow* existing_window = list ? GTK_WINDOW(list->data) : NULL;

    if (existing_window) {
        gtk_window_present(existing_window);
    } else {
        // ...
  // Generated flutter code
  // ...
    }
}

Note:
Linux distributions running Wayland have strict focus behaviors, and therefore, the above solution is inadequate for focusing the window. Instead, a request to show the window is made, and might appear as a notification.

Windows

By default, Windows desktop applications allow multiple instances to run simultaneously. To enforce single-instance behavior in a Flutter Windows app, you can make modifications to the windows/runner/main.cpp file.

Step 1: Create a Named Mutex

By creating a named mutex (short for “mutual exclusion”) when starting a Flutter application, we can use it to enforce single-instance behavior.

Add the following code to the beginning of the wWinMain() function:

#define APP_MUTEX_NAME L"Global\\MyUniqueFlutterAppMutex"

int APIENTRY wWinMain(...) {
 HANDLE hMutex = CreateMutex(NULL, TRUE, APP_MUTEX_NAME);
 if (GetLastError() == ERROR_ALREADY_EXISTS) {
     // App is already running.
 }

 ...
}

Step 2: Find and Present the Existing Window

When the application detects that another instance is running, it brings the existing app window to the foreground instead of launching a new one. If you use something like window_manager to change the name of the window, the single instance will still be enforced; however, focusing on the existing window will not work.

Add the following code inside the if (GetLastError() == ERROR_ALREADY_EXISTS) block:

HWND hwnd = FindWindow(NULL, APP_WINDOW_NAME);
if (hwnd) {
    ShowWindow(hwnd, SW_RESTORE);
    SetForegroundWindow(hwnd);
}
return 0;

Step 3: Set a Unique Window Name

The window title serves as the identifier for FindWindow.

Update the Create call for the main window to use a unique name defined as APP_WINDOW_NAME:

#define APP_WINDOW_NAME L"unique_title"

if (!window.Create(APP_WINDOW_NAME, origin, size)) {
    return EXIT_FAILURE;
}

When the application exits or crashes, the mutex is automatically destroyed.

Add this code before the return EXIT_SUCCESS; statement:

if (hMutex) {
    ReleaseMutex(hMutex);
}

macOS

Flutter on macOS typically handles single-instance applications quite well on its own. When you launch a second instance of an application, the system usually brings the existing instance to the front. However, you can ensure the behavior by modifying the macos/Runner/AppDelegate.swift file.

Step 1: Override the applicationShouldHandleReopen Function

This method ensures that if the app is already running and a new instance is opened, the existing window is brought to the foreground.

Add this function to the AppDelegate class.

override func applicationShouldHandleReopen(_ sender: NSApplication, hasVisibleWindows flag: Bool) -> Bool {
  if !flag {
      sender.windows.forEach { $0.makeKeyAndOrderFront(self) }
  }
  return true
}

Step 2: Override the applicationDidFinishLaunching Function

This function is called when the app finishes launching. It checks if there are other instances of the app running. If it finds another instance, it will activate the existing one and terminate the new instance.

Add this function to the AppDelegate class.

override func applicationDidFinishLaunching(_ notification: Notification) {
  super.applicationDidFinishLaunching(notification)

  let appBundleIdentifier = Bundle.main.bundleIdentifier!

  let runningApps = NSRunningApplication.runningApplications(withBundleIdentifier: appBundleIdentifier)
  if runningApps.count > 1 {
      // App is already running, activate the existing instance
      runningApps.first?.activate(options: .activateIgnoringOtherApps)
      NSApp.terminate(nil)
  }
}

Summary

By implementing single-instance functionality, you can provide a polished and user-friendly experience for desktop applications. Whether you choose to use existing packages or dive into platform-specific code, Flutter makes it possible to achieve this seamlessly across platforms. The choice ultimately depends on your app’s requirements and your development preferences.

Flutter Desktop Single-Instance Applications was originally published in Industrial Flutter on Medium, where people are continuing the conversation by highlighting and responding to this story.

Developing an application for desktop or embedded platforms often means choosing between Qt Widgets and Qt Quick to develop the UI. There are pros and cons to each. Qt, being the flexible framework that it is, lets you combine these in various ways. How you should integrate these APIs will depend on what you’re trying to achieve. In this entry I will show you how to display Qt Widget windows on an application written primarily using Qt Quick.

Why Show a Qt Widget Window in a Qt Quick App

Qt Quick is great for software that puts emphasis on visual language. A graphics pipeline, based around the Qt Quick Scene Graph, will efficiently render your UI using the GPU. This means UI elements can be drawn, decorated, and animated efficiently as long as you pick the right tools (e.g. Shaders, Animators, and Qt’s Shapes API instead of its implementation of HTML’s Canvas).

From the Scene Graph also stem some of Quick’s weaknesses. UI elements that in other applications would extend outside of the application’s window, such as tool tips and the ComboBoxcontrol, can only be rendered inside of Qt Quick windows. When you see other app’s tooltips and dropdowns extend beyond the window, those items are being rendered onto a separate windows; one without window decorations (a.k.a. borderless windows). Rendering everything on the same window helps ensure your app will be compatible with systems that can only display a single window at a time, such as Android and iOS, but it could result in wasted space if your app targets PC desktop environments.

QML ComboBox is confined to the Qt Quick window while the Widgets ComboBox extends beyond the window

Qt lets us combine Widgets and Quick in a few ways. The most common approach is to embed a Qt Quick view into your Widgets app, using QQuickWidget. That approach is fitting for applications that primarily use Widgets. Another option is to render Widgets inside a Qt Quick component, by rendering it through a QQuickPaintedItem. However, this component will be limited to the same window confines as the rest of the items in your Quick window and it won’t benefit from Scene Graph rendering optimizations, meaning you get the worst of both worlds.

A third solution is to open widget windows from your Qt Quick apps. This has none of the aforementioned drawbacks, however, the approach has a couple of drawback of its own. First, the app would need to be run from a multi-window per screen capable environment. Second, widget windows are not parentable to Qt Quick windows; meaning certain window z-stack related features, such as setting window modality to Qt::WindowModal, won’t have effect on the triggering window when a Widget is opened from Qt Quick. You can work around that by setting modality to Qt::ApplicationModal instead, if you’re okay with blocking all other windows for modality.

Displaying Widget windows in Qt Quick applications has been useful to me in the past, and is something I haven’t seen documented anywhere, hence this tutorial.

How to Show a Qt Widget Window in a Qt Quick App

Architecture Big Picture

Displaying a Qt Widget window from Qt Quick is simpler than it seems. You’ll need two classes:

1. The class that represents the widget window.
2. A class to interface from QML, that hosts and instantiates the window.

You might be tempted to forgo the interface class and instantiate the widget directly. However, this would result in a crash. We’ll display the widget window by running Widget::show from the interface class.

Update CMakeLists.txt

In addition to those classes, you’ll also need to make sure that your app links to both Qt::Quickand Qt::Widgets libraries. Here's what that looks like for a CMake project

// Locate libraries
find_package(Qt6 6.5 REQUIRED COMPONENTS
    Quick
    Widgets)

// Link build target to libraries
target_link_libraries(${TARGET_NAME} PRIVATE
    Qt6::Quick
    Qt6::Widgets)

// Replace ${TARGET_NAME} with the name of your target executable

Update main.cpp

In addition to that, in main.cpp you'll need to use QApplication in place of QGuiApplication.

QApplication app(argc, argv);

The Interface Layer

Prepare the interface layer as you would any C++ based Quick component. By this I mean: derive from QObject, and use the Q_OBJECT and QML_ELEMENT macros to make your class available from QML.

// widgetFormHandler.h
#pragma once
class WidgetFormHandler : public QObject
{
    Q_OBJECT
    QML_ELEMENT

public:
    explicit WidgetFormHandler(QObject *parent = nullptr);
};

// widgetFormHandler.cpp

WidgetFormHandler::WidgetFormHandler(QObject *parent)
    : QObject(parent)
{
}

Instantiating the Widgets Window

// widgetFormHandler.h
#pragma once
class WidgetsForm;
class WidgetFormHandler : public QObject
{
    Q_OBJECT
    QML_ELEMENT

public:
    explicit WidgetFormHandler(QObject *parent = nullptr);
~WidgetFormHandler();

private:
    std::unique_ptr<WidgetsForm> m_window;
}

Use std::make_unique in the constructor to initialize the unique pointer to m_window.

Define the instantiating class’ destructor to ensure the pointers are de-alocated, thus preventing memory leaks. If you stick to using smart pointers, C++ will do all the work for you; simply use the default destructor, like I do here. Make sure to define it outside of the class’ header; some compilers have trouble dealing with the destructor when it’s defined inside the header.

// widgetFormHandler.cpp
#include "widgetFormHandler.h"

WidgetFormHandler::WidgetFormHandler(QObject *parent)
    : QObject(parent)
    , m_window(std::make_unique<WidgetsForm>())
{
    // ...
}

WidgetFormHandler::~WidgetFormHandler() = default;

Make Properties Available to QML

Now we want to make properties from the widget available in QML. How we do this will depend on the property and on whether we will manipulate the property’s value from both directions or only from one side only and update on the other.

Let’s look at a bi-directional example in which we add the ability to control the visible state of the widget window from QML. We’ll add a property called “visible” to the C++ interface so that it matches the visible that we get from Qt Quick windows in QML. Declare the property using Q_PROPERTY. Use READ and WRITE functions to control the window's state.

Here’s what that would look like:

// widgetFormHandler.h
#pragma once
class WidgetsForm;

class WidgetFormHandler : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibleChanged)

public:
    explicit WidgetFormHandler(QObject *parent = nullptr);    
~WidgetFormHandler();
    const bool isVisible();    
    void setVisible(bool);

signals:
    void visibleChanged();

private:
    std::unique_ptr<WidgetsForm> m_window;
};

// widgetFormHandler.cpp
#include "widgetFormHandler.h"

#include "widgetForm.h"

WidgetFormHandler::WidgetFormHandler(QObject *parent)
    : QObject(parent)
    , m_window(std::make_unique<WidgetsForm>())
{
    // Hide window by default
    m_window->setVisible(false);
}
WidgetFormHandler::~WidgetFormHandler() = default;
const bool WidgetFormHandler::isVisible()
{
    return m_window->isVisible();
}
void WidgetFormHandler::setVisible(bool visible)
{
    m_window->setVisible(visible);
    emit visibleChanged();
}

To make this bi-directional, set NOTIFY to a signal that allows the property to be updated in QML after it being emitted and emit the signal where applicable. We emit it from setVisible in this class, however if QWidget had a signal that emitted when its visible state changed, I would also make a connection between that signal and that of our handler’s visibleChanged. However, that isn’t the case, so we have to make sure to emit it ourselves.

Make Signals Available to QML

Develop the widget window as you would any other widget. If you use UI forms, go to the header file and create a signal for each action that you wish to relay over to QML.

In this example we’ll relay a button press from the UI file, so we’ll create a button named pushButton in our ui file:

Now add a buttonClicked signal to our header:

// widgetsForm.h
#pragma once
#include <QWidget>

namespace Ui
{
    class WidgetsForm;
}

class WidgetsForm : public QWidget
{
    Q_OBJECT
public:
    explicit WidgetsForm(QWidget *parent = nullptr);
    ~WidgetsForm();
signals:
    void buttonClicked();
    // Signal to expose button click from Widgets window
private:
    std::unique_ptr<Ui::WidgetsForm> ui;
};

Once again, we use a unique pointer, this time to hold the ui object. This is better than what Qt Creator templates give us because it means C++ handles the memory management for us and we can avoid the need for a delete statement in the destructor.

In the window’s constructor, we make a connection between the UI’s button’s signal and the one that we’ve created to relay the signal for exposure.

// widgetsForm.cpp
#include "widgetsform.h"
#include "ui_widgetsform.h"

WidgetsForm::WidgetsForm(QWidget *parent)
    : QWidget(parent)
    , ui(std::make_unique<Ui::WidgetsForm>())
{
    ui->setupUi(this);
    // Expose click
    connect(ui->pushButton, &QPushButton::clicked, this, &WidgetsForm::buttonClicked);
}

WidgetsForm::~WidgetsForm() = default;

Before we connect the exposed signal to the QML interface, we need another signal on the interface to expose our event over to QML. Here I add qmlSignalEmitter signal for that purpose:

// widgetFormHandler.h
[..]
signals:
    void visibleChanged();
    void qmlSignalEmitter();  // Signal to relay button press to QML
[..]

To complete all the connections, go to the interface layer’s constructor and make a connection between your window class’ signal and that of the interface layer. This would look as follows:

// widgetFormHandler.cpp
[..]
WidgetFormHandler::WidgetFormHandler(QObject *parent)
    : QObject(parent)
    , m_window(std::make_unique<WidgetsForm>())
{
    QObject::connect(m_window, &WidgetsForm::buttonClicked, this,
    &WidgetFormHandler::qmlSignalEmitter);
}
[..]

By connecting one emitter to another emitter we keep each classes’ concerns separate and reduce the amount of boilerplate code, making our code easier to maintain.

Over at the QML, we connect to qmlSignalEmitter using the on prefix. It would look like this:

import NameOfAppQmlModule  // Should match qt_add_qml_module's URI on CMake

WidgetFormHandler {
    id: fontWidgetsForm

    visible: true  // Make the Widgets window visible from QML

    onQmlSignalEmitter: () => {
        console.log("Button pressed in widgets")  // Log QPushButton's click event from QML
    }
}

Final Product

I’ve prepared a demo app where you can see this technique in action. The demo displays text that bounces around the screen like an old DVD player’s logo would. You change the text and font through two identical forms, one implemented in QML and the other done in Widgets. The code presented in this tutorial comes from that demo app.

Example code: https://github.com/KDABLabs/kdabtv/tree/master/Blog-projects/Widget-window-in-Qt-Quick-app

https://youtu.be/IGGBhsFESR4

The moving text should work on all desktop systems except for Wayland sessions on Linux. That is because I’m animating the window’s absolute position (which is restricted in Wayland for security reasons) rather than the contents inside a window. This has the benefit of not obstructing other applications, since the moving window that contains the text would capture mouse inputs if clicked, preventing those from reaching the application behind it.

Real World Use Case

The first time I employed this technique was in my FOSS project, QPrompt. I use it there to provide a custom font dialog that doubles as a text preview. Having a custom dialog gives me full control over formatting options presented to users, and for this app we only needed a preview for large text and a combo box to choose among system fonts. QPrompt is also open source, you can find the source code relevant to this technique here: https://github.com/Cuperino/QPrompt-Teleprompter/blob/main/src/systemfontchooserdialog.h

Thank you for reading. I hope you’ll find this useful. A big thank you to David Faure for suggesting the use of C++ unique pointers as well as reviewing the code along with Renato and my team.

If there are other techniques that you’d like for us to try or showcase, let us know.

Display Widget Windows in Qt Quick Application was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Modern embedded software development demands precision, adaptability, and efficiency. Projects often span diverse hardware platforms, each with unique needs, and must meet strict real-time requirements. Best practices like containerized environments, streamlined CI pipelines, and incremental refactoring, often provide the edge needed to deliver reliable, high-performance solutions. Let’s look at these practices to help enhance your development processes and overcome some common challenges in embedded workflows.

Building in isolation

Containers are revolutionizing embedded software development by providing a controlled and consistent environment for builds. This approach prevents conflicts between your local development environment and the build environment, offering much-needed clarity and stability. Three key reasons why containers matter in embedded development:

• Consistency across teams: Developers working on different platforms can rely on identical, preconfigured environments. This eliminates discrepancies caused by local setup variations and ensures reproducibility. For example, you could use a container to encapsulate your development toolchain so that every team member compiles with identical compiler versions and configurations.
• CI/CD integration: Containers enable rapid deployment of isolated build instances within CI pipelines. This means you can spin up a new container for each build and run tests in parallel without interfering with other processes.
• Simplified onboarding: New developers can pull a container image and start building without manually configuring dependencies, saving hours of setup time.

While containers add overhead during setup, the long-term gains in reliability and scalability make them a great fit for embedded workflows. For a deeper dive on containers, check out the Developer’s Guide to Containers by my colleague, Andrew Hayzen.

Managing dependencies

Most embedded projects rely on numerous dependencies, including runtime libraries, open-source components, and developer tools. It’s important to manage these dependencies effectively to keep your builds stable and your CI pipelines smooth.

One approach is to build all critical dependencies from source. For smaller, fast-moving dependencies, this approach provides flexibility and ensures alignment with project requirements. However, for more stable, less frequently updated dependencies, using package managers or pre-built binaries to distribute precompiled packages can save time and reduce the overall burden on your team. Striking the right balance between the two approaches depends on the complexity and size of your specific stack.

CI done right

When CI works well, it’s a developer’s best friend. Automated builds, testing, static analysis, and code sanitizers provide fast feedback and improve code quality. However, CI is more challenging in embedded development due to hardware constraints, cross-compilation requirements, and resource limitations. Yet, a well-tuned CI pipeline can transform how teams work. Here are a few ways to optimize your pipeline:

1. HIL testing: Integrating physical hardware into your CI pipeline is a great way to test firmware against real-world conditions. While emulators are useful, they can miss hardware-specific bugs like race conditions and timing issues — things you might be able to catch with a cluster of low-cost boards like Raspberry Pis in your test framework.
2. Parallelized builds and tests: Leveraging cloud services or dedicated build servers to run parallel jobs, can reduce feedback time. This approach is useful for tasks like testing multiple product configurations by distributing the workload across several nodes.
3. Static and dynamic analysis tools: Tools like clang-tidy or Google Sanitizers can be integrated into the CI pipeline to catch potential issues early. Static analysis ensures code adheres to best practices, while dynamic analysis detects runtime errors.

Iterative improvements without stalling development

Refactoring is essential for long-term maintainability of clean, manageable code, but it must be handled carefully to avoid disrupting ongoing development. Instead of halting production for massive rewrites, adopt a trunk-based development approach using ‘atomic commits’ where changes for small, self-contained updates are merged into the main branch at least once a day. Atomic commits work because short-lived branches and incremental changes keep the codebase current while avoiding the pitfalls of stale, long-lived branches and minimizing integration headaches. Plus, every commit is tested via CI pipelines and static analysis, catching issues early.

However, sometimes you can’t avoid working with large-scale changes, particularly in big codebases. Examples include migrating hardware abstraction layers and rewriting critical middleware. In these cases, you may want to create parallel APIs that allow old and new implementations to coexist temporarily. This approach enables incremental migration of refactored modules to the new API while maintaining the legacy API for unaffected components. Both APIs should coexist only for as long as it takes to confidently migrate and validate all dependent modules, Validation should include unit, integration, and hardware tests. Once all refactored modules have been integrated into the new API, the legacy API should be deprecated.

By refactoring incrementally in this way and maintaining stability, teams can avoid the risk of system-wide disruptions, turning what is often considered a very disruptive process into a seamless part of development.

Key takeaways

By embracing modern development practices tailored to the unique challenges of embedded systems, teams can achieve faster cleaner, more maintainable codebases without sacrificing productivity. Strategies discussed in this blog include:

• Leveraging containers for consistent build environments
• Building dependencies wisely, balancing flexibility with efficiency
• Optimizing CI pipelines for fast, actionable feedback
• Approaching refactoring incrementally for minimal disruption

These practices are just the tip of the iceberg in creating a robust development environment. For those looking to delve deeper into optimizing their development workflows, our full whitepaper on General Development offers more insights and additional strategies tailored to modern software teams.

Streamlining Development by Mastering Modern Development Practices was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

by Sean Harmer, originally published on kdab.com/resources

Introduction

We all need to log out data from time to time whilst developing or even when running in production. Sometimes this will be to stdout, stderr, a logfile, the system logger etc. Using tools such as spdlog and fmt make this a breeze. However, one thing has been causing an itch that I've wanted to scratch for a while now. How can we do nicely formatted printing of nested structs and maintaining indentation?

Given some simple nested structs such as:

struct Vec2 {
    int x;
    int y;
};

struct Size {
    int width;
    int height;
};

struct Rect {
    Vec2 position;
    Size size;
};

...
Rect rect{ { 0, 20 }, { 800, 600 } };
spdlog::info("rect: {}", rect);

We would like to easily obtain output similar to this:

rect: Rect2 {
    position: Vec2 {
        x: 0
        y: 20
    }
    size: Size2 {
        width: 800
        height: 600
    }
}

We hope this short blog post can show you a way to do exactly that using fmt in a way that you can easily extend to your own types and customise further. This can then be used with spdlog or similar to make your log files and debug output kinder to humans.

General Approach

The excellent fmt documentation explains how to provide support for formatting your own types by providing a specialization of the fmt::formatter template and taking advantage of subclassing or composing an existing fmt::formatter to take advantage of the facilities they provide (e.g. parsing formatting specifications).

The slight design issue we have here is that fmt is oriented around the concept of formatting independent lines of output. We need to have some state or context that is persistent across multiple lines, namely the amount to indent.

Examining the above layout of the output we see that we can break the output of a struct down to the following steps:

1. Output the struct name and an opening curly brace at a given level of indentation and a newline.
2. Increase the indentation by one level
3. Iterate over the struct members and for each, output the member label, a colon, and the member value. If the member is itself a struct, go back to 1. If the member is a “scalar”, output a newline.
4. Decrease the indentation by one level
5. Output a closing curly brace and a newline.

Our approach to this, is to provide a new class that specializes the fmt::formatter template that manages the above steps. In order to easily allow customisation to output your own types taking advantage of the indenting facilities, we allow inheriting from our custom formatter using the Curiously Recurring Template Pattern (CRTP). This nicely allows customisation without any runtime overhead from virtual functions and allows us to provide most of the boilerplate in the base class.

If you just want to see the final code, you can play with it here.

The Indenting Formatter

To specialize the fmt::formatter template we must provide two functions:

• constexpr auto parse(fmt::format_parse_context &ctx) -> fmt::format_parse_context::iterator
• auto format(auto v, fmt::format_context &ctx) const -> fmt::format_context::iterator

We won’t go into the gory details of the former in this article. You can read it for yourself in the final code if you are interested. Suffice it to say it is concerned with extracting the initial indentation level if the user specifies one.

The format function

The format function in the indenting formatter is responsible for orchestrating the algorithm outlined above. Let’s tackle the easy part first: outputting the type name and the opening curly brace. We require the developer to subclass using the CRTP which we can then make use of to output the custom type’s name via a name() member function on the derived class:

auto format(auto v, fmt::format_context &ctx) const
        -> fmt::format_context::iterator
{
    const T &derived = static_cast<const T &>(\*this);
    fmt::format_to(ctx.out(), "{} {{\\n", derived.name());

// Get indentation level and output members
    ...

// Output the closing curly brace and return the context iterator
    ...
}

The fmt::format_to function works just like the regular fmt::format function except that it outputs to an output iterator which in this case is part of the format_context we are provided with. The remaining arguments are the format specification followed by any variables to be substituted in. For more information, there is an excellent guide to the fmt syntax.

To output the type name we obtain a reference to the derived object and call the derived.name() member function. The format specification just says to output the substituted type name, followed by a literal curly brace, followed by a newline.

Extracting the indentation level

The parse functions provided by formatters are responsible for extracting the formatting instructions and keeping track of explicitly numbered arguments. Using explicitly numbered arguments allows the substitutions to appear in an explicit order rather than the implicit left-to-right ordering in the format specification. Within our format function, we must handle the case of numbered arguments when deciding upon which indentation level to use. To do so, we can lookup argument values from the format specification and operate upon them.

auto format(auto v, fmt::format_context &ctx) const
        -> fmt::format_context::iterator
{
    // Output type name
    ...

    // Extract indentation level to use
    size_t indentToUse;
    if (!hasArgumentIndex) {
        // Implicit argument ordering - use indent from parse() function
        indentToUse = indent;
    } else {
        // Numbered argument ordering
        auto argValue = ctx.arg(argumentIndex);
        auto extractSizeT = \[\]<typename U>(const U &v) -> size_t {
            if constexpr (std::is_integral_v<U>) {
                return v;
            } else {
                throw std::format_error("Wrong argument datatype provided");
                return {};
            }
        };

        indentToUse = fmt::visit_format_arg(extractSizeT, argValue);
    }

    // Output members and closing brace
    ...
}

Full credit to my amazing colleague Giuseppe D’Angelo for making this work!

Formatting values and structs

Armed with our current indentation level we can now increment this and delegate outputting of the members to the derived class:

auto format(auto v, fmt::format_context &ctx) const
        -> fmt::format_context::iterator
{
    // Output type name
    ...

    // Extract indentation level to use
    ...

    // Output members and closing brace
    memberIndent = indentToUse + 4; // Yes it's a magic number
    derived.format_members(v, ctx);

    // Output closing curly brace
    ...
}

From the above, we see that we expect a derived class to now also provide another member function called format_members. This function should output the members that you care about. To make life easier for developers, let's make a couple of functions on our base class that can be used by the derived classes to format a "scalar" value as well as a member that is itself another struct:

void format_scalar(std::string_view label, auto v, fmt::format_context &ctx) const
{
    fmt::format_to(ctx.out(), "{:{}}{}: {}\\n", "", memberIndent, label, v);
}

void format_struct(std::string_view label, auto v, fmt::format_context &ctx) const
{
    fmt::format_to(ctx.out(), "{:{}}{}: {:{}}\\n", "", memberIndent, label, v, memberIndent);
}

Both of these functions make use of a neat feature in fmt that allows us to dynamically specify the format specification. In this case we want to be able to specify the indentation used when a derived class calls one of these helpers.

Notice the format specifications in both of these functions include some nested substitutions. When dealing with implicitly ordered substitution placeholders, they are ordered from left to right and then from outside in. The inner placeholders are prefixed by a colon which means the value that gets substituted in will be used to specify the indentation level.

The use of an empty string for the surrounding placeholder just means that fmt will expand that placeholder to be the specified width - i.e. pad it with spaces. The following color-coded diagrams should hopefully illustrate how the various parts of the format specifications map to the substituted values.

Substitutions for format_scalar

Substitutions for format_struct

One thing of note here is that in the format_struct function (see Fig. 2), the purple width specifier is used to provide the current member indentation level as the surrounding blue placeholder recurses into the indenting formatter for the child struct. It is the format() and format_struct() functions that form the recursive pair to properly indent the output with the level of nesting.

One final piece is just combining the dynamic width trick with outputting a literal closing curly brace to finish off the output for a given struct:

auto format(auto v, fmt::format_context &ctx) const
        -> fmt::format_context::iterator
{
    // Output type name
    ...

    // Extract indentation level to use
    ...

    // Output members and closing brace
    ...

    // Output closing curly brace
    return fmt::format_to(ctx.out(), "{:{}}}}", "", indentToUse);
}

Providing a concrete indenting formatter

With all of the above elements in place, writing a custom subclass of the indenting formatter for your own type is very easy. Here is the subclass for the Vec2 type used in the motivating example:

template<>
struct fmt::formatter<Vec2> : indenting_formatter<fmt::formatter<Vec2>> {
    auto name() const -> std::string_view { return "Vec2"; }

    auto format_members(Vec2 v, fmt::format_context &ctx) const
            -> fmt::format_context::iterator
    {
        format_scalar("x", v.x, ctx);
        format_scalar("y", v.y, ctx);
        return ctx.out();
    }
};

All we have to do is:

• Inherit using CRTP.
• Provide a name() function to return the type name as we wish to see it.
• Provide a format_members() function that will typically make use of the format_scalar()and format_struct() helpers we built above.

Going further

There are a few improvements we could make to the above. For example, the indentation is hard-wired to 4 spaces per level but this could be made configurable. Providing another helper on the base class for formatting values wrapped in a std::optional that could print "<Not Set>" when the optional does not contain a value. Adding support for arrays in whatever format you wish to present them. Even nicer would be if we could generate the derived indenting formatter classes automatically using reflection.

Using the indenting formatter within spdlog is completely transparent since it uses fmt under the hood. If you are using spdlog in your projects, you may also be interested in the KDSpdSetup library that allows you to configure all of your logging from a simple toml file.

We hope that you found this article an interesting exercise in abusing the fmt api slightly to provide a more human readable output of your types. Feel free to take the code and use it as you wish.

Indented Printing with fmt was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

by Javier Cordero, originally published on kdab.com/resources

As a person who enjoys responsive designs, I like to resize apps and see how quickly the UI updates after the resize. If you’re making an app with Qt Quick, you’ll sometimes find that, as the window size increases, the UI will lag behind for one or more frames, revealing a white background on two of the window’s edges, that usually looks out of place on desktop applications.

Why is the color background revealed when the window size is increased?

This issue stems from the fact that Qt Quick windows will render a background color, white by default, before the position of elements is updated by the scene graph, which lags at least one frame behind the resize because it uses a frame buffer. If the default background is white, that means the QML window itself is not aware of your application’s theme and that is intentional; after all, only desktop apps need to be aware of the background color used by native applications.

Qt Quick Controls, however, are theme aware, and that may include your platform’s theme. This is why, when you make an app for Windows, if you set a Label against the application’s default white background, it will look just fine. But when that app is moved to macOS or a Linux distribution with a dark theme, the label’s text will be drawn with a light color to match that theme, and that will make it nearly impossible to read against the default white background.

One solution for that issue is to place these components against a control that extends through a large area, such as a Pane. Qt Quick Controls’ theme awareness will ensure the right background color is used. However, controls are only drawn within the window, so when the window is resized, its true background color will seep through — and that’s the issue with which we’re concerned. The correct solution is to set the window’s background to the system’s or the theme’s background color, which will make the frame buffer’s lag far less noticeable during resizing.

How to Make Qt Quick Window Backgrounds Aware of Your System’s Theme

Setting a background color is as simple as assigning a value to the “color” property of the window, like so:

Window {
    color: "lightblue"
}

To have it match the background color of native apps, use QML’s SystemPallete type, as follows:

import QtQuick
Window {
    color: systemPalette.window
    SystemPalette {
        id: systemPalette
    }
}

Here you can find the various default styles used by Qt Quick for each supported platform. By making use of SystemPalette, the appropriate background color for the current platform will be chosen.

It is important to note that, using SystemPalette, the background color will be chosen based on the current platform and not on which QML style has actually been applied, which may differ if your app makes use of a fixed style for all platforms.

Platform Style vs. Fixed Style

As an alternative to following the platform’s theme, you could provide a uniform experience for all platforms by enforcing one style for all. There are minor performance advantages to having a fixed style for all systems, but these only tend to matter on low-end embedded hardware, where every cycle counts. There you could use Compile-Time Style Selection, so the QML compiler knows which style is in use and can generate C++ code for bindings.

If you are creating a desktop application, your theming choice should be based, not on performance, but on the level of system integration and the user experience you wish to provide. A photography application might benefit from having a dark mode at all times so the picture colors can pop. An e-mail client, on the other hand, might do better integrating with the system’s theme or allowing users to choose between a light theme and a dark theme. Light backgrounds generally provide better contrast, which makes them a good default choice for emails. However, users may prefer the system theme or a dark theme, if it’s easier on their eyes.

Crafting Seamless and Theme-Aware Qt Quick Applications

By thoughtfully managing your Qt Quick application’s window background color, you can significantly improve its responsiveness and aesthetic integration with the host platform. Whether you opt to align with the system’s theme using SystemPalette or enforce a fixed style for uniformity, your choice should reflect the needs of your application and its users. Balancing system integration, performance, and user experience ensures your app not only looks great across platforms but also feels natural to use, providing a polished and professional result. With these tools and insights, you can create dynamic, theme-aware applications that stand out in usability and design.

Integrate QML Window’s Background with the System’s Color Palette was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Shipping your product to customers is where some real challenges in software development begin. Once it lands in customers’ hands, delivering the expected and necessary software updates can be a complicated task.

Here’s a breakdown of some key considerations to keep your product, and your customers, running smoothly, even after your product has shipped.

Getting updates to users

The way you handle software updates depends on both your device and your users. Some products rely on users to manually update the device firmware. This approach puts more work on the end user but can be an acceptable simple first step if your user base is technically savvy. It eliminates some complexity to have your customers download the firmware directly from your website and install it themselves via USB, onboard storage, or even through a desktop app.

If you go this route, however, you’ll want to think about implementing safety measures. Corrupt firmware files or interruptions in the update process can brick the device. Consider using dual A/B firmware loads to ensure there’s always a working version available if the update fails.

The alternative to manually delivered updates is over-the-air (OTA) installation. This has a lot of advantages, from hands-off operation to remote updates. They can also be made more resilient to interruptions since the software can validate the image is on the system before installing it. The biggest downside is the complexity of programming an OTA solution, as well as mandating that the device has access to the internet (although it’s increasingly rare that things don’t).

To auto-update or not?

Automatic updates sound like a great idea — customers always get the latest features and security patches without having to lift a finger. But it’s important to weigh the pros and cons. Auto-updates can force your device to go offline for maintenance, which might annoy users if it happens at the wrong time. Imagine a smart keyless lock performing an update while someone is locked out of their home or a medical device updating itself during a critical procedure.

For devices that are constantly in use or have critical uptime requirements, it’s worth considering an opt-in model for updates. Even if auto-updates are the default, make sure the feature can be easily turned off or postponed by the user.

Keeping data intact

Updates should never wipe out user data. It’s one thing to install fresh code, but if configuration files or user data are lost in the process, you’ve got a problem. To avoid this, you need to manage your file versions carefully and develop a process for migrating data forward in a way that’s backwards-compatible if necessary.

If your product allows rolling back to earlier versions of firmware, ensure that data migration works both ways. For configuration files, text formats like JSON can be a lifesaver. If you need to roll back, any keys added by newer versions can be ignored. When updating, any missing keys mean that you need to provide a default value. Plus JSON files are human-readable, which is especially useful if you need to debug configuration files directly.

Preparing your software for the world

When it’s time to release an update, you’ll need a robust process in place. First things first: every update needs a unique version number. This is essential for tracking issues and ensuring that customers are using the correct version of the software.

To streamline the process, compress your firmware files to save space during download and storage. And don’t forget security: all your update files should be digitally signed to prevent tampering or corruption. Maintaining a well-organized in-house library of all releases, along with tagging customer-facing versions in your source control, will make life easier when you need to dig up old binaries for testing or debugging.

Even if your product uses containers like Docker, the same principles apply. How will customers get the updates? How will the integrity of the files be verified? And, just as important, how can you ensure that the process of getting these files into your device is bulletproof?

Testing before shipping

Quality assurance is crucial, and there’s no substitute for testing the entire product before it hits customer hands. Unit testing by developers is important, but you need to go beyond that. Whether it’s an in-house team or outsourced specialists, someone needs to test the fully integrated product.

Once your product is in the field, you’ll also need a plan to recover from potential bugs in the update process. Can your customer reset the device to factory defaults and restore it from a stable firmware version? If so, make sure that reset process covers everything, from the obvious to the less visible, like persistent hardware or file system states that users might not even know exist.

Planning for future updates

Before your product is in the field, you’ll need to decide how often you want to push bug fixes and security patches. Will updates roll out on a regular schedule, or will you wait until a critical mass of fixes is ready? Some customers may even require their own private branches for high-priority fixes, depending on their contracts or support agreements.

It’s worth discussing these considerations with your team upfront so that everyone’s aligned on the update strategy. This can help avoid last-minute scrambles and keep your customers happy in the long run.

Final thoughts

Shipping a product isn’t just about getting it into the customer’s hands. It’s about ensuring that, once it’s there, it can continue to evolve, improve, and remain secure. Whether through manual updates or automated processes, thoughtful planning and thorough testing will make sure your product stays at its best long after it’s left your warehouse.

By keeping these best practices in mind, you can ensure that your embedded Linux device not only works today but will continue to function — and improve — well into the future.

For more on related topics, including important up-front decisions that need to be made at the outset of a project, explore our whitepaper, Designing Your First Embedded Linux Device: Framing the Development Process.

Delivering Software Updates: The Last Mile of Product Development was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Adopting proven practices like continuous integration (CI) and continuous deployment (CD) is a key part of modern software design. These methodologies enhance software quality and team productivity while shortening development cycles — what’s not to love? Arguably, it’s the short-term pain of getting these systems installed and configured for your environment and the long-term pain of maintaining them. But you’ve come to the right place; this blog gives you some practical tips in getting your CI/CD system spun up that avoid common pitfalls and maximize long-term benefits.

Not sure you want to take the plunge? Here’s why we recommend CI/CD practices.

Advantages of CI/CD

CI/CD practices have several advantages that that can transform your development process. Here are some key reasons why implementing them is a smart move:

• Comprehensive and efficient testing: CI runs all relevant tests, not just those immediately impacted by recent changes, so it uncovers potential hidden issues. This allows developers to focus on local testing for quick checks but rely on CI for thorough, asynchronous testing that can run on separate systems in the background.
• Automated code reviews: A CI system acts as an additional, automated code reviewer. By building and testing code across all platforms, it can catch issues that might be missed in peer reviews, all without consuming valuable engineering resources. Plus, it allows you to easily incorporate tools for static analysis, linting, and sanitizing to enhance code quality and stability.
• Consistent code style: CI enforces consistent code formatting across all source files, eliminating style discrepancies that can affect readability. This standardization is crucial for large, distributed teams and helps avoid time-consuming (and unproductive) debates during peer reviews.
• No testing needed: It might seem like you need a fully developed set of unit tests to take advantage of CI. You don’t. You can still get a lot of value from cross-compiling on multiple platforms, doing static analysis, and running format checkers. And once your CI system is in place, a small number of effective tests can validate critical items. Don’t be discouraged if you’ve just started creating your test suites — building up a few tests at a time as you find and fix bugs still offers a lot of benefit.

Essential components for effective CI/CD setup

A successful CI/CD pipeline requires several key components to function smoothly. These elements work together to ensure that your development process is efficient, scalable, and reliable. Here are a few basic requirements to get started:

• Repository: Hopefully this is already a given, but if it’s not, you’ll need a shared repository for all developers.
• CI servers: You need hardware to do the CI builds but it can be on-prem or in-cloud and we’ll discuss the pros and cons of both later. But if you’re considering an on-prem solution, you’ll want at least one dedicated CI server, and possibly multiple CI worker machines based on project size and complexity.
• Team structure: You need people that know in detail how the CI system works. But whether it’s better to have a dedicated specialist or to distribute the necessary CI knowledge and responsibilities throughout the team probably depends on which CI tools you choose. In either case, you probably want to have 2 or 3 people who are part-time focused on CI tasks who can help other team members troubleshoot and act as backup if your dedicated person is unavailable.
• Toolchain: Cloud-based tools like GitHub Actions provide easy, pre-configured setups. But a cloud system isn’t always the best idea. For an on-prem system like Jenkins or Buildbot, expect to invest time in server setup, software installation, worker machine configuration, and ongoing OS maintenance. You also want automation tools like Chef or Ansible to allow systems to run unattended so that the CI/CD system can reset and reboot them automatically.

Cloud versus on-premises

Deciding whether to host your CI/CD system in the cloud or on-premises is an important decision that impacts cost, scalability, and security. Each option has its advantages and disadvantages, depending on your specific needs and constraints. Here are some key considerations to help guide your choice:

Cloud pros

• Simplicity and quick setup: Cloud systems are ready to use without hardware acquisition, installation, or configuration.
• Scalability: Easy scalability is an advantage of cloud-based systems, allowing for quick adjustments to resources as development needs change.
• Integration: Cloud hosted CI/CD systems integrate easily with cloud hosting platforms like GitHub and GitLab, especially when you leverage built-in automation tools like GitHub Actions.

Cloud cons

• Cost: Continuous operation can lead to significant cloud processing and storage fees, especially with frequent multiplatform builds.
• Data privacy and security: Regulations such as GDPR or specific industry requirements may restrict cloud usage, necessitating on-prem solutions for enhanced control over data security and compliance.

On-prem pros

• Cost control: On-prem can be more cost-effective in the long run, especially if large-scale CI operations are needed frequently.
• Data security: On-prem provides control over data privacy and security, which can be essential for regulation

On-prem cons

• Maintenance: On-prem systems need to be maintained, repaired, and upgraded, requiring ongoing engineering or IT resources.
• Spin-up: While a cloud system is available instantly, an on-prem equivalent needs to be built and configured, which can take a significant amount of time, especially if it’s the company’s first.

Optimizing CI builds

CI is only effective when developers use it. And if your CI system is too slow to deliver results, developers will tend to ignore it. How do you achieve a balance of speed and thoroughness?

Essentially, you want to implement two main CI builds — one that allows a quick per-commit build and one that builds nightly. The quick build is run throughout the day as developers make commits and it should use pre-built dependencies and caches for optimal speed. The nightly build executes a full build from scratch every night with all static checks and installers.

If developers are in the same time zone, the two builds can be run on the same machine — otherwise, you’ll want a dedicated machine for nightly builds. You may also consider a third CI build for packaging. This can be used for teams that share external updates, such as customer testing or third-party validation services. This build is somewhere between the quick and nightly builds — it can rely on bits of the quick build (including packaging if it’s fast enough), while benefitting from the deeper coverage of the nightly build.

Ensuring reliability in your CI workflow

In a CI workflow, using developer tools like GitHub, Gerrit, and Bitbucket, CI-gated check-ins are essential. These tools ensure that all changes are validated by the CI system, confirming that commits pass necessary compiler and unit tests before merging into the main branch. Making CI gating optional can lead to the dangerous practice of skipping or bypassing CI builds, which significantly reducing a system’s value.

That’s why your CI system needs to be rock solid. If it frequently experiences issues — like excessive build times due to network problems — developers might be tempted to bypass CI checks altogether. Continuous maintenance is essential to ensure CI systems function effectively as a non-negotiable part of the development workflow.

Where to go next?

This short blog just scratches the surface on CI/CD. If you’re looking for more information and details on some of the most commonly used CI/CD tools — and when you might be better off choosing one over the other — check out our CI/CD best practice guide.

From Integration to Deployment: A CI/CD Primer was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

by Leon Matthes and Matt Aber, originally published on kdab.com/resources

In a recent email, Leon Matthes from KDAB highlighted some of his go-to command line tools for everyday use on Unix. His recommendations sparked a lively exchange among our colleagues, each sharing their own favorite utilities.

Many of these tools offer efficient alternatives to standard Unix programs, speeding up the workflow or otherwise enriching the development experience.

This article aims to serve as a resource for the wider community, encouraging others to explore these tools and upgrade their command line setup for improved productivity.

The following common Unix tools are listed in this document, with their alternatives specified in their respective sections:

• cd
• ls
• man
• find
• grep
• cat
• diff / git diff

Additionally, there are some tools here that do not replace common programs, but are extremely useful when working in a shell environment. These are broken into two broad categories:

• prompts & shells
• misc.

Many of these tools can be considered examples of the “rewrite it in Rust” approach (RIIR), which in this document will be denoted with Ferris the crab: 🦀

Finally, there is a bonus Rust crate listed at the end that is helpful for writing CLI programs of your own.

Note: for scripting, stick with standard Unix tools, as they’re more widely distributed and will work in most other Unix environments. The tools in this article are meant to improve quality of life working within your own shell environment on a daily basis.

cd

autojump

autojump is an alternative to cd, invoked with the command j. It jumps to what it determines to be the best fit for whatever directory name you give it. For example, j cxx-qt will change directory to the cxx-qt directory, even if it’s nested several levels deep from the current working directory.

If autojump doesn’t prioritize a directory correctly, its priority weight can be increased or decreased. j -i XXX will increase the priority weight of the current working directory by XXX, while j -d XXX will do the opposite and decrease the weight accordingly.

autojump also supports opening a file browser at a matched location rather than cd'ing into it, by invoking jo rather than j.

Unfortunately, autojump has not been in active development for the past two years, and can break in some environments. The next tool, zoxide, will be more reliable if autojump breaks for you.

zoxide 🦀

zoxide is a similar program to autojump, actually drawing inspiration from it. Invoked with the command z, it remembers paths that have been visited in the past and matches the best fitting directory. The tool also supports interactive selection of the correct match via the zi command, which uses the tool fzf for fuzzy finding. fzf is listed later in this article.

zoxide can also be used the same way as plain cd, and can target absolute and relative paths. It can be configured to be invoked from the j and ji commands, or even cd to fully replace the cdcommand.

Finally, it is implemented in Rust, resulting in better performance than autojump.

ls

lsd 🦀

lsd is a more feature-rich version of ls, including colors, icons, tree-view, additional formatting, and more. It is also highly configurable through a yaml config file.

eza 🦀

eza is a small, fast ls rewrite that knows about symlinks, extended attributes, and git, and has support for hyperlinks. Similar to lsd, it supports colors and icons, which are configurable with a yaml config file.

man

tldr

This project has several clients written in different languages. The most mature client is an npm package.

tldr is an alternative to using man for most common use cases. It is a collection of pages that provides brief descriptions and usage examples for loads of programs, standard Unix and otherwise. It’s much faster if you don’t need to read about every option in detail in order to find the correct way to invoke a command or select the proper option quickly.

For example, if the man page for tar is too long to read when looking for the right option to do something, simply running tldr tar will show a list of examples that will usually have the options you need.

cheat.sh / cht.sh

cheat.sh and its associated shellscript cht.sh, provide access to a superpowered aggregation of cheatsheets for programming languages and CLI tools, including tldr pages and other sources.

It has a great system for querying cheatsheets, and you don’t even need to install a tool (though you can), as the query response can be retrieved by curl. It’s also usable inside editors, for easy referencing while programming.

The cheatsheet sources also include StackOverflow answers, which allow for flexible usage like so:

$ cht.sh js parse json

A nice way to use cheat.sh without installing anything is to put the following function in your .bashrc or .zshrc:

function cheat() {
    if ! curl -s "cheat.sh/${*//\ /+}"; then
        echo "Failed to get the cheatsheet" >&2
        return 1
    fi
}

Then you can use it like

$ cheat tar

or

$ cheat cpp number to string

find

fd 🦀

fd is an alternative for many use cases of find.

While it is not as powerful as find, it is designed to be faster and more user-friendly for the majority of find's use cases.

No more find -name .rs -- just use fd .rs and you’re good to go.

fd is super fast and will search through your entire filesystem in a matter of seconds (Leon recorded 1.4s on his machine with 177GB of files).

By default, fd will not include any hidden files that are ignored by .gitignore, which is very useful as it doesn’t give you any random junk in your build directory and speeds up the search even further.

Use --hidden and --no-ignore (or -H and -I, respectively) to search for everything.

fzf

fzf is a fuzzy-finder that can match files, command history, processes, hostnames, bookmarks, git commits, and more, with interactive selection. It’s also usable as a vim or neovim plugin.

grep

ripgrep 🦀

ripgrep (rg as a command) provides an incredibly fast grep alternative with a simpler interface.

Did you ever have to wait for grep to finish searching a directory or had to look up the right options for specific usage? Well, no more! Ripgrep will search the contents of large build directories within milliseconds.

Just running rg Q_PROPERTY will search through the entire current directory if you don’t pipe something into it, which is very convenient and the way it should have been in the first place. The output is also a lot friendlier and easier to read.

Like fd, use --hidden and --no-ignore to search in hidden and ignored directories/files.

cat

bat 🦀

bat, written by the creator of fd, is a superpowered Rust rewrite of cat. It provides syntax highlighting, line numbers, support for displaying non-printable characters, support for showing multiple files at once, and pipes to less by default for large output. It can also be integrated with fzf, find, fd, ripgrep (rg), git show, git diff, man, and more. A tool you'll read about later in this document, delta, uses bat as a dependency to display diffs.

diff / git diff

diff-so-fancy

diff-so-fancy is an alternative to vanilla git diff that improves readability, with better formatting, colors, and highlighting. Configure git to use diffsofancy as its pager, and git diff will provide the more readable diffsofancy output.

delta 🦀

delta is an alternative to diffsofancy that’s written in Rust. It includes additional features, like line numbers, syntax highlighting, side-by-side, improved navigation between files in large diffs, hyperlinked commit hashes, improvements for display of git blame and merge conflicts, and the ability to syntax-highlight grep output. delta uses bat under the hood and, as such, they can share color themes.

prompts & shells

starship 🦀

starship is a prompt written in Rust, which can be used with a number of popular shells including bash, zsh, fish, and even Windows shells like cmd and PowerShell.

The prompt is both stylish and informative, providing information like git branch, versioning, and more in the prompt itself. It also indicates the time length of command execution, whenever the run lasts for more than a few seconds — very helpful for gauging the duration of a build. This prompt should be utilized with a NerdFont for icon support.

Starship is also extremely configurable, so any details can be omitted or added; the look and feel of the prompt can be completely customized, etc.

zsh prompts & plugins

Some shell users argue that switching from bash is definitely worthwhile, with zsh being the favorite choice for many. It’s highly configurable and has a rich plugin ecosystem.

oh-my-zsh is a zsh framework that makes completions, searching in history, the prompt, etc., much nicer than the defaults. It can, of course, be tweaked much further from there. If you find oh-my-zsh to be a bit bloated, there are more lightweight alternatives such as ZimFW or Zinit.

Some zsh plugins can also serve as alternatives to previously mentioned tools. There are quite a few useful plugins listed here (they should work with any plugin manager): https://github.com/unixorn/awesome-zsh-plugins.

Some that stand out include:

• zsh-vi-mode
• a proper Vim mode for the terminal, much better than the default one
• fast-syntax-highlighting
• nice while-you-type syntax highlighting in the shell
• fzf-marks
• alternative workflow to zoxide and similar cd improvements
• this can also be used with bash
• zsh-autoenv
• customize environment variables by directory, similar to the tool direnv mentioned later

Note: If you are interested in switching away from bash but don’t like zsh, consider trying fish.

Update Systems

topgrade 🦀

topgrade is a tool which conveniently updates several package managers with one command.

Just run topgrade and every package manager under the sun will be updated, one after the other. This even includes flatpaks and updates to your systems package manager, very convenient.

Misc.

direnv

direnv is an extension for several common Unix shells, focused on environment management. More specifically, it is intended to unclutter .profile and export different environment variables depending on the current directory.

On each prompt, it checks for the existence of a .envrc file in the current directory, otherwise looking for .env, and loads or unloads environment variables accordingly. It’s a single executable and very fast.

direnv is also extensible with bash files in .config.

blobdrop

blobdrop enables drag-n-drop of files from a terminal window, which can be very convenient when using the command line as a file browser. It was written by fellow kdabian Magnus Gross

bonus!

clap

bonus is not quite a tool, but a Rust crate used frequently for writing CLI tools, called clap.

clap is used in the codebases of a majority of the Rust tools in this document, as it’s incredibly useful. It’s the reason most Rust CLI tools have great UX.

Using the derive feature, you can simply mark up a struct of data you need from your command line arguments and clap will generate a beautiful and convenient CLI interface for you. Just take a look at the derive documentation to get an idea of what this looks like.

Other Tools

We hope these tools can improve your workflow, as they certainly make our lives on the command line far more enjoyable.

If you have any additions to this list, feel free to discuss them in the comments.

CLI++: Upgrade Your Command Line was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

by David Faure, originally published on kdab.com/resources

In this third blog post of the Model/View Drag and Drop series (part 1 and part 2), the idea is to implement dropping onto items, rather than in between items. QListWidget and QTableWidget have out of the box support for replacing the value of existing items when doing that, but there aren’t many use cases for that. What is much more common is to associate a custom semantic to such a drop. For instance, the examples detailed below show email folders and their contents, and dropping an email onto another folder will move (or copy) the email into that folder.

With Model/View separation

Example code can be found here for flat models and here for tree models.

Setting up the view on the drag side

☑ Call view->setDragDropMode(QAbstractItemView::DragOnly)
unless of course the same view should also support drops. In our example, only emails can be dragged, and only folders allow drops, so the drag and drop sides are distinct.

☑ Call view->setDragDropOverwriteMode(...)
true if moving should clear cells, false if moving should remove rows.
Note that the default is true for QTableView and false for QListView and QTreeView. In our example, we want to remove emails that have been moved elsewhere, so false is correct.

☑ Call view->setDefaultDropAction(Qt::MoveAction) so that the drag defaults to a move and not a copy, adjust as needed

Setting up the model on the drag side

To implement dragging items out of a model, you need to implement the following — this is very similar to the section of the same name in the previous blog post, obviously:

class EmailsModel : public QAbstractTableModel
{
    ~~~
    Qt::ItemFlags flags(const QModelIndex &index) const override
    {
        if (!index.isValid())
            return {};
        return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsDragEnabled;
    }

    // the default is "copy only", change it
    Qt::DropActions supportedDragActions() const override { return Qt::MoveAction | Qt::CopyAction; }

    QMimeData *mimeData(const QModelIndexList &indexes) const override;

    bool removeRows(int position, int rows, const QModelIndex &parent) override;

☑ Reimplement flags() to add Qt::ItemIsDragEnabled in the case of a valid index

☑ Reimplement supportedDragActions() to return Qt::MoveAction | Qt::CopyAction or whichever you want to support (the default is CopyAction only).

☑ Reimplement mimeData() to serialize the complete data for the dragged items. If the views are always in the same process, you can get away with serializing only node pointers (if you have that) and application PID (to refuse dropping onto another process). See the previous part of this blog series for more details.

☑ Reimplement removeRows(), it will be called after a successful drop with MoveAction. An example implementation looks like this:

bool EmailsModel::removeRows(int position, int rows, const QModelIndex &parent)
{
    beginRemoveRows(parent, position, position + rows - 1);
    for (int row = 0; row < rows; ++row) {
        m_emailFolder->emails.removeAt(position);
    }
    endRemoveRows();
    return true;
}

Setting up the view on the drop side

☑ Call view->setDragDropMode(QAbstractItemView::DropOnly) unless of course it supports dragging too. In our example, we can drop onto email folders but we cannot reorganize the folders, so DropOnly is correct.

Setting up the model on the drop side

To implement dropping items into a model’s existing items, you need to do the following:

class FoldersModel : public QAbstractTableModel
{
    ~~~    
    Qt::ItemFlags flags(const QModelIndex &index) const override
    {
        CHECK_flags(index);
        if (!index.isValid())
            return {}; // do not allow dropping between items
        if (index.column() > 0)
            return Qt::ItemIsEnabled | Qt::ItemIsSelectable; // don't drop on other columns
        return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsDropEnabled;
    }

    // the default is "copy only", change it
    Qt::DropActions supportedDropActions() const override { return Qt::MoveAction | Qt::CopyAction; }
  
    QStringList mimeTypes() const override { return {QString::fromLatin1(s_emailsMimeType)}; }
  
    bool dropMimeData(const QMimeData *mimeData, Qt::DropAction action, int row, int column, const QModelIndex &parent) override;
};

☑ Reimplement flags()
For a valid index (and only in that case), add Qt::ItemIsDropEnabled. As you can see, you can also restrict drops to column 0, which can be more sensible when using QTreeView (the user should drop onto the folder name, not onto the folder size).

☑ Reimplement supportedDropActions() to return Qt::MoveAction | Qt::CopyAction or whichever you want to support (the default is CopyAction only).

☑ Reimplement mimeTypes() - the list should include the MIME type used by the drag model.

☑ Reimplement dropMimeData()
to deserialize the data and handle the drop.
This could mean calling setData() to replace item contents, or anything else that should happen on a drop: in the email example, this is where we copy or move the email into the destination folder. Once you're done, return true, so that the drag side then deletes the dragged rows by calling removeRows() on its model.

bool FoldersModel::dropMimeData(const QMimeData *mimeData, Qt::DropAction action, int row, int column, const QModelIndex &parent)
{
    ~~~  // safety checks, see full example code

    EmailFolder *destFolder = folderForIndex(parent);

    const QByteArray encodedData = mimeData->data(s_emailsMimeType);
    QDataStream stream(encodedData);
    ~~~ // code to detect and reject dropping onto the folder currently holding those emails

    while (!stream.atEnd()) {
        QString email;
        stream >> email;
        destFolder->emails.append(email);
    }
    emit dataChanged(parent, parent); // update count

    return true; // let the view handle deletion on the source side by calling removeRows there
}

Using item widgets

Example code:

• QListWidget
• QTableWidget
• QTreeWidget

On the “drag” side

☑ Call widget->setDragDropMode(QAbstractItemView::DragOnly) or DragDrop if it should support both

☑ Call widget->setDefaultDropAction(Qt::MoveAction) so that the drag defaults to a move and not a copy, adjust as needed

☑ Reimplement Widget::mimeData() to serialize the complete data for the dragged items. If the views are always in the same process, you can get away with serializing only item pointers and application PID (to refuse dropping onto another process). In our email folders example we also serialize the pointer to the source folder (where the emails come from) so that we can detect dropping onto the same folder (which should do nothing).

To serialize pointers in QDataStream, cast them to quintptr, see the example code for details.

On the “drop” side

☑ Call widget->setDragDropMode(QAbstractItemView::DropOnly) or DragDrop if it should support both

☑ Call widget->setDragDropOverwriteMode(true) for a minor improvement: no forbidden cursor when moving the drag between folders. Instead Qt only computes drop positions which are onto items, as we want here.

☑ Reimplement Widget::mimeTypes() and return the same name as the one used on the drag side's mimeData

☑ Reimplement Widget::dropMimeData() (note that the signature is different between QListWidget, QTableWidget and QTreeWidget) This is where you deserialize the data and handle the drop. In the email example, this is where we copy or move the email into the destination folder.

Make sure to do all of the following:

• any necessary behind the scenes work (in our case, moving the actual email)
• updating the UI (creating or deleting items as needed)

This is a case where proper model/view separation is actually much simpler.

Improvements to Qt

While writing and testing these code examples, I improved the following things in Qt, in addition to those listed in the previous blog posts:

• QTBUG-2553 QTreeView with setAutoExpandDelay() collapses items while dragging over it, fixed in Qt 6.8.1

Conclusion

I hope you enjoyed this blog post series and learned a few things.

Model/View Drag and Drop in Qt — Part 3: Moving/copying items onto existing items was originally published in KDAB Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.