Martin's Blog

FPM: Cleaning up folders when uninstalling RPM packages

Mon, 02 Jan 2023 09:52:00 +0000

When working in a larger organization (or you just want to ensure you are using a properly defined development environment), it is always a good idea packaging software components you are using and installing them from these packages to ensure all developers use the same version of needed modules to build and run a project.

When working on Linux, there are two major package formats being used: The Debian format (using the *.deb file name extension) and the RedHat Package Manager (RPM) format (which uses the *.rpm) file name extension.

Building such packages from scratch can sometimes be a little cumbersome, but to ease this, there’s a nice little tool available: fpm!

fpm is a nice little tool, written in Ruby, which can be used to create a variety of package formats without struggle. It can easily be installed; just make sure you install Ruby first and then you can get fpm using Ruby’s own package manager gem like this:

# Assuming you are on an RPM based Linux:
sudo yum install -y ruby

# To build RPM packages, you'll also need rpm-build:
sudo yum install -y rpm-build

# Use gem to install fpm:
gem install fpm

Now, if you want to create an RPM package for - le’t say - a program HelloWorld, this could look like:

VERSION=1.2.3

curl -o helloworld-$VERSION.tar.gz https://example.com/releases/helloworld-$VERSION.tar.gz
tar -xf helloworld-$VERSION.tar.gz
cd helloworld

# Let's assume the software is built using cmake:
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/helloworld/$VERSION
cmake --build build

# Install it into a temporary location:
DESTDIR=$PWD/install_root cmake --install build

# And now, package it:
fpm \
    -C $PWD/install_root \
    -s dir \
    -t rpm \
    --version $VERSION \
    --name helloworld_$VERSION \
    --rpm-autoreq \
    --description "HelloWorld, version $VERSION" \
    $(ls $PWD/install_root)

👉 Note, that we include the version number also in the installation location and the package name. That way, different versions of the package can be installed next to each other - this can be useful when you need to quickly switch between versions of a module, especially if you use tools like environment modules on top.

Now, the above works and should produce a usable RPM package (well, given you package something real 😉). But there is a but here!

RPM has a notion of ownership over files and directories. An RPM package produced like that will only own the files that get installed. However, if we uninstall the package, we will notice that the folder structure will still be there (although all files properly have been removed)!

In most cases, this isn’t too bad (empty folders usually don’t do any harm). But sometimes they are! In my case, I packaged Python and over time released an updated version of the same Python interpreter that updated older versions of the package in-place. An update is mostly the same as an uninstall of the old and install of the new version. What happened? In my case, I had the new version of Python properly installed, but there were empty folders of some packages that got installed alongside Python in the modules folder. These empty folders caused issues with Python, because Python’s built in plugin mechanism found these empty folders and treated them like they where still valid. This caused very strange and hard to track down failures with some of our scripts that used that Python installation (not to mention that these bugs were not reproducible when installing only the new package e.g. within a Docker container 😉).

So, long story short: How to get rid of these extra folders after an upgrade/uninstall? Easy, we need to tell fpm/rpm-build, that the package we create owns the folders it installs:

fpm \
    -C $PWD/install_root \
    -s dir \
    -t rpm \
    --version $VERSION \
    --name helloworld_$VERSION \
    --rpm-autoreq \
    --description "HelloWorld, version $VERSION" \
    --directories /opt/helloworld/$VERSION \
    $(ls $PWD/install_root)

We simply use the --directories option, which will mark the folder (recursively) as being owned by our package. Uninstalling our package will no longer leave empty folders around!

⚠️ Please note that we specify the full installation prefix above! In the end,we don’t want our package to own more folders as it actually does 😉

Installing and Using a `pip` Package From Within a Python Script

Tue, 18 Aug 2020 18:25:00 +0000

Recently, I needed the capability to install a package from PyPI via the pip package manager from within a Python script and use it from within the very same script. As it was a bit trial and error and I had to go through several different sites and posts to finally find a working solution, I thought I’d share it here (aka so that I’ll be able to copy and paste this the next time I need it myself 👿):

def install_pip_package(pkg, install_name=None):
    import importlib
    import sys
    from subprocess import check_call
    import site

    try:
        importlib.import_module(pkg)
    except ImportError:
        if install_name is None:
            install_name = pkg
        check_call([
            sys.executable,
            "-m", "pip", "install", install_name
        ])
        importlib.reload(site)
    finally:
        importlib.import_module(pkg)

Okay, so that’s the whole magic. By default, you can call this function like this:

# Ensure `termcolor` is installed:
install_pip_package("termcolor")

# Now we can safely import it:
import termcolor

In case the name for importing the module and installing it via pip differ, you can call it like this:

# Ensure the `dialog` module is available, if not, install it,
# but keep in mind it is called `pythondialog` in PyPI:
install_pip_package("dialog", install_name="pythondialog")

# Now we can safely use it:
import dialog

As I like to explain things, here some words on the function itself:

We try to import the desired module to see if it already is there.
If this yields an ImportError, we know it is not present. In this case, we de facto use python -m pip install <install_name> to install it.
If this succeeds, we explicitly reload the site module, which ensures that the next attempt to import the just installed module will in fact find it.

Well, that’s it. Maybe a site note that such an approach will not replace proper deployment and packaging dependencies as an app. But in environments like the one I needed this for, it is super handy 😉

Qt for Android - Installing A Library Built With qmake Into The Qt Directory

Tue, 21 May 2019 20:30:00 +0000

Have you ever written a library on top of Qt? It is actually quite ease. Consider we have a very simple library called my-qt-lib, with the following structure:

.
├── myqtlib.cpp
├── my-qt-lib_global.h
├── myqtlib.h
└── my-qt-lib.pro

This is a very simple skeleton which Qt Creator usually creates for your in case you ask it to create a shared library project. Let’s have a closer look at the file my-qt-lib.pro, where we need to apply some changes:

QT       -= gui

TARGET = my-qt-lib
TEMPLATE = lib

DEFINES += MYQTLIB_LIBRARY

DEFINES += QT_DEPRECATED_WARNINGS

SOURCES += \
        myqtlib.cpp

HEADERS += \
        myqtlib.h \
        my-qt-lib_global.h 

# Install the library into the Qt 
# installation's libraries directory:
target.path = $$[QT_INSTALL_LIBS]
INSTALLS += target

# Install the headers into the Qt 
# installation's include directory:
headers.files = myqtlib.h my-qt-lib_global.h
headers.path = $$[QT_INSTALL_HEADERS]
INSTALLS += headers

That’s also quite simple and mostly what Qt Creator is able to create for you automatically. The interesting thing are the few lines at the end. We set up custom installation paths for our library, pointing it to libraries installation location of the current Qt installation (by using $$[QT_INSTALL_LIBS]). In addition, we create a custom install target headers, which we use to copy the header files into the Qt installation (concrete, into the include directory, which we get by using $$[QT_INSTALL_HEADERS]).

With this setup, we can do the following to install our library into a Qt installation:

mkdir build-linux-x86_64
cd build-linux-x86_64
$HOME/Qt/5.12.2/gcc_64/bin/qmake ..
make
make install

The last line will actually copy the library plus header files into the Qt installation. To better understand, what gets copied where, let’s tweak it and see which files would get copied:

make install INSTALL_ROOT=$PWD/tmp

This will basically do a “fake” installation into the sub-directory tmp/ inside the current directory. Let’s check the content of this directory:

tmp
└── home
    └── martin
        └── Qt
            └── 5.12.2
                └── gcc_64
                    ├── include
                    │   ├── my-qt-lib_global.h
                    │   └── myqtlib.h
                    └── lib
                        ├── libmy-qt-lib.so -> libmy-qt-lib.so.1.0.0
                        ├── libmy-qt-lib.so.1 -> libmy-qt-lib.so.1.0.0
                        ├── libmy-qt-lib.so.1.0 -> libmy-qt-lib.so.1.0.0
                        └── libmy-qt-lib.so.1.0.0

Cool, exactly what we would have expected: The process would have copied the library (including some symlinks, which are typical for a Linux installation of a library) as well as the header files into the Qt installation. Great.

What is this useful for? Well, if you have an addon library for Qt, you can easily install it into your Qt installation and every other library or app building against this Qt will be able to use your library. Fancy, isn’t it?

There is just one little issue. Let’s assume we also want to use our library on Android. Consequentially, we need to install it into our Android Qt installation. Let’s go:

# Make the path to the Android NDK known:
export ANDROID_NDK_ROOT=$HOME/Android/android-ndk-r19c
mkdir build-android-armv7
cd build-android-armv7
$HOME/Qt/5.12.2/android_armv7/bin/qmake ..
make
make install INSTALL_ROOT=$PWD/tmp

The last line will again install the library into a temporary directory, so we can check the installation:

tmp/
├── home
│   └── martin
│       └── Qt
│           └── 5.12.2
│               └── android_armv7
│                   └── include
│                       ├── my-qt-lib_global.h
│                       └── myqtlib.h
└── libs
    └── armeabi-v7a
        └── libmy-qt-lib.so

Uff, and here, something is wrong. The headers are correctly installed. However, the library would get installed into /libs/armeabi-v7a. What went wrong?

The answer is simple: qmake has some built in magic when it comes to Android. You can read about this in detail in the official docs. The point is: This magic prevents us from installing the library where we want it to land.

As always, the solution to this issue is not as well documented as it could be, but sooner or later you land in Qt’s bug tracker and there indeed you find a solution. We just need to remove the android_install configuration option:

QT       -= gui

TARGET = my-qt-lib
TEMPLATE = lib

DEFINES += MYQTLIB_LIBRARY

DEFINES += QT_DEPRECATED_WARNINGS

SOURCES += \
        myqtlib.cpp

HEADERS += \
        myqtlib.h \
        my-qt-lib_global.h 

target.path = $$[QT_INSTALL_LIBS]
INSTALLS += target

headers.files = myqtlib.h my-qt-lib_global.h
headers.path = $$[QT_INSTALL_HEADERS]
INSTALLS += headers

# Disable qmake's magic for installing libraries
# on android:
CONFIG -= android_install

If we repeat the above steps to build and install the library, we now get the expected results:

tmp
└── home
    └── martin
        └── Qt
            └── 5.12.2
                └── android_armv7
                    ├── include
                    │   ├── my-qt-lib_global.h
                    │   └── myqtlib.h
                    └── lib
                        └── libmy-qt-lib.so

Very good! However, we now have a little problem: If someone uses our library as a sub-module inside another project, he will not be able to use qmake’s magic in case he targets Android. So in case we want to allow both (installation of the library into the Qt installation when building standalone as well as deployment to the standard location in case of it is built as part of another project), we can just keep the *.pro file as it is and instead modify the call to qmake on the command line:

# Disable the special Android library handling on command line:
$HOME/Qt/5.12.2/android_armv7/bin/qmake CONFIG-=android_install ..

# And now proceed as usual:
make
make install

Using DelegateModel in QML for Sorting and Filtering

Tue, 15 Jan 2019 18:27:00 +0000

When developing with the Qt framework, you might already have stumbled over its model view framework, consisting of classes like QAbstractItemModel, QTreeView and QSortFilterProxyModel.

In particular, QSortFilterProxyModel is interesting: In the simplest case, you create a model which you plug into a view, which displays the exposed items. The QSortFilterProxyModel in turn can be plugged in between the source model and the view. With its help, we can easily filter the list of items or reorder them. We can even stack such proxy models, which allows to combine different sorting and filtering criteria as needed.

When it comes to QML, things are not quite as straightforward. Of course, you can continue to use the C++ model/view classes, including proxy models. However, if you have models which are defined solely on QML side, or you want to make use of the possibility of QML to use other kinds of models - in the simplest case a simple integer number - you need another solution.

Here, the QML type DelegateModel proofs to be useful. Although it is (in my opinion) not documented as good as it could be, we will use it to implement sorting and filtering of an arbitrary source model in QML. However, a warning ahead: If you have larger data sets, consider sticking with the C++ model classes instead! Only use this approach when you know that your data sets are relatively small, so the impact of doing the filtering in the QML layer does not impact your app too much.

Where We Want to Get to: Model Sorting and Filtering in QML

Let’s start with what we want to archive in the end: A GUI which has a simple model (a number which the user can change) and which we filter and sort entirely in QML. The code for such an application could roughly look like this:

import QtQuick 2.9
import QtQuick.Window 2.3
import QtQuick.Controls 2.4
import QtQml.Models 2.3
import QtQuick.Layouts 1.3

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    SortFilterModel {
        id: delegateModel

        lessThan: function(left, right) {
            if (view.sortLexically) {
                return left.modelData.toString() < right.modelData.toString();
            } else {
                return left.modelData < right.modelData;
            }
        }

        filterAcceptsItem: function(item) {
            return item.modelData % 2 == view.remainder;
        }

        model: numberOfItems.value
        delegate: Text {
            id: item

            text: qsTr("This is item #%1").arg(modelData)
        }
    }

    ListView {
        id: view

        property int remainder: 0
        property bool sortLexically: true

        anchors {
            left: parent.left
            right: parent.right
            top: parent.top
            bottom: controls.top
        }

        model: delegateModel
        onRemainderChanged: delegateModel.update()
        onSortLexicallyChanged: delegateModel.update()
    }

    RowLayout {
        id: controls

        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom

        Button {
            text: qsTr("Toggle odd/even")
            onClicked: view.remainder = (view.remainder + 1) % 2;
        }

        Button {
            text: qsTr("Toggle sort")
            onClicked: view.sortLexically = !view.sortLexically
        }

        Slider {
            id: numberOfItems
            from: 10
            to: 1000
            value: 100
            Layout.fillWidth: true
        }
    }
}

And this is how it looks like when rendered:

Quick Walk Through the App’s Code

Let’s quickly jump through the app code. First, we instantiate out SortFilterModel (we are going to look at it’s code later):

    SortFilterModel {
        id: delegateModel

        lessThan: function(left, right) {
            if (view.sortLexically) {
                return left.modelData.toString() < right.modelData.toString();
            } else {
                return left.modelData < right.modelData;
            }
        }

        filterAcceptsItem: function(item) {
            return item.modelData % 2 == view.remainder;
        }

        model: numberOfItems.value
        delegate: Text {
            id: item

            text: qsTr("This is item #%1").arg(modelData)
        }
    }

It is basically what would you expect:

We assign a comparison function to the lessThan property. This function is used to compare two entries of the model and returns true of the left one is less than the right one, otherwise false. The parameters left and right are containers which have the same properties that otherwise would be exposed to the delegate of a view when used with the same model as source.
Similarly, the function assigned to filterAcceptsItem gets and item and returns true if the item shall be visible or false otherwise.
The model property is set to the source model we want to use. We can set it to any model we need, be it a QAbstractItemModel, a list or even a simple number. In our case, we bind it to a number (which is coming from a slider component defined later).
Finally, we define a delegate. This is what is potentially new and unexpected, as usually we set delegates in Views. However, as we use a DelegateModel as a base, we set the delegate in the model.

Next, let’s continue with the view:

    ListView {
        id: view

        property int remainder: 0
        property bool sortLexically: true

        anchors {
            left: parent.left
            right: parent.right
            top: parent.top
            bottom: controls.top
        }

        model: delegateModel
        onRemainderChanged: delegateModel.update()
        onSortLexicallyChanged: delegateModel.update()
    }

Nothing special. We anchor the view and set it’s model property to our SortFilterModel. We also define two helper properties (remainder and sortLexically) which we use to control sorting and filtering. Note that we call the update() method of our SortFilterModel when these two properties change to apply the changed sorting and filtering. Also note that we do not set a delegate in the view, as this is coming from our source model.

Finally, we add some controls to change sorting, filtering and also the amount of items in the source model:

    RowLayout {
        id: controls

        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom

        Button {
            text: qsTr("Toggle odd/even")
            onClicked: view.remainder = (view.remainder + 1) % 2;
        }

        Button {
            text: qsTr("Toggle sort")
            onClicked: view.sortLexically = !view.sortLexically
        }

        Slider {
            id: numberOfItems
            from: 10
            to: 1000
            value: 100
            Layout.fillWidth: true
        }
    }

We have…

One button to toggle between odd and even numbers.
A second button is used to toggle between lexical and natural ordering of entries.
Finally, there is a slider which we can use to change the amount of items in the source model.

So far, so good. Next, let’s have a look at how the SortFilterModel is implemented.

The `SortFilterModel` Component

import QtQuick 2.9
import QtQml.Models 2.3

DelegateModel {
    id: delegateModel

    property var lessThan: function(left, right) { return true; }
    property var filterAcceptsItem: function(item) { return true; }

    function update() {
        if (items.count > 0) {
            items.setGroups(0, items.count, "items");
        }

        // Step 1: Filter items
        var visible = [];
        for (var i = 0; i < items.count; ++i) {
            var item = items.get(i);
            if (filterAcceptsItem(item.model)) {
                visible.push(item);
            }
        }

        // Step 2: Sort the list of visible items
        visible.sort(function(a, b) {
            return lessThan(a.model, b.model) ? -1 : 1;
        });

        // Step 3: Add all items to the visible group:
        for (i = 0; i < visible.length; ++i) {
            item = visible[i];
            item.inVisible = true;
            if (item.visibleIndex !== i) {
                visibleItems.move(item.visibleIndex, i, 1);
            }
        }
    }

    items.onChanged: update()
    onLessThanChanged: update()
    onFilterAcceptsItemChanged: update()

    groups: DelegateModelGroup {
        id: visibleItems

        name: "visible"
        includeByDefault: false
    }

    filterOnGroup: "visible"
}

As announced, the component is based on QML’s DelegateModel. We actually just need a few things on top:

    property var lessThan: function(left, right) { return true; }
    property var filterAcceptsItem: function(item) { return true; }

We define two properties lessThan and filterAcceptsItem which shall be set to functions which are then used to sort and filter our source model. The defaults are set such that the SortFilterModel basically does an identity mapping, not changing the sorting nor visibility of the items from the source model.

    groups: DelegateModelGroup {
        id: visibleItems

        name: "visible"
        includeByDefault: false
    }

    filterOnGroup: "visible"

This is something you have to get used to: A DelegateModel uses different so called groups to do its job. It has a default, built in group called items, which is always there. By assigning a single or a list of DelegateModelGroup instances we can add more groups. For our model, we add just one new group visible, into which we put the items that are visible later on. By setting it’s includeByDefault property to false, items added to the source model are not automatically added to the group. Lastly, we set the filterOnGroup property to visible. This way, only items that are in the visible group are shown.

    function update() {
        if (items.count > 0) {
            items.setGroups(0, items.count, "items");
        }

        // Step 1: Filter items
        var visible = [];
        for (var i = 0; i < items.count; ++i) {
            var item = items.get(i);
            if (filterAcceptsItem(item.model)) {
                visible.push(item);
            }
        }

        // Step 2: Sort the list of visible items
        visible.sort(function(a, b) {
            return lessThan(a.model, b.model) ? -1 : 1;
        });

        // Step 3: Add all items to the visible group:
        for (i = 0; i < visible.length; ++i) {
            item = visible[i];
            item.inVisible = true;
            if (item.visibleIndex !== i) {
                visibleItems.move(item.visibleIndex, i, 1);
            }
        }
    }

This function is basically the heart of the implementation. It is responsible for filtering and sorting the source model. For this, the model does the following:

It removes all items from the visible group, by calling the setGroups method of the items group. It can be used to change the group memberships of several items at once. In our case, we set the group membership of all items in the items group to only ["item"] only.
Second, we gather all items that are visible. For this, we iterate over all items in the items group. Each entry has a member model, which contains a map of all properties from the source model - this is basically what would also be visible in a delegate. If the filterAcceptsItem function returns true, we put the item into an intermediate JavaScript array.
After we gathered all visible items, we call the sort method on the JavaScript array, passing in a custom sort function, which is based on our lessThan function.
In the last step, we iterate over the intermediate list of items and put them into the visible group. This is done by setting each item’s inVisible property to true. In addition, we use the mode method of the visible group to move the item to the position where it belongs to.

That’s it!

But… Can It Deal With Something Else Like Numbers, Too?

Sure 😎

The great thing about using DelegateModel as base for our SortFilterModel, we can deal with everything: The DelegateModel just passes through the properties of the items in the source model. In the simplest case where you have a number as model, we only have the modelData attribute, which is the index of the item in the source model. If we use something else, the attributes are transparently made available, too. Here’s an example using a ListModel as base:

import QtQuick 2.9
import QtQuick.Window 2.3
import QtQuick.Controls 2.4
import QtQml.Models 2.3
import QtQuick.Layouts 1.3

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    ListModel {
        id: nameModel
        ListElement { name: "Alice"; team: "Crypto" }
        ListElement { name: "Bob"; team: "Crypto" }
        ListElement { name: "Jane"; team: "QA" }
        ListElement { name: "Victor"; team: "QA" }
        ListElement { name: "Wendy"; team: "Graphics" }
    }

    RowLayout {
        id: controls

        anchors {
            left: parent.left
            top: parent.top
            right: parent.right
        }

        TextField {
            id: nameFilter
            placeholderText: qsTr("Search by name...")
            Layout.fillWidth: true
            onTextChanged: sortFilterModel.update()
        }

        RadioButton {
            id: sortByName
            checked: true
            text: qsTr("Sort by name")
            onCheckedChanged: sortFilterModel.update()
        }

        RadioButton {
            text: qsTr("Sort by team")
        }
    }

    SortFilterModel {
        id: sortFilterModel
        model: nameModel
        filterAcceptsItem: function(item) {
            return item.name.includes(nameFilter.text)
        }
        lessThan: function(left, right) {
            if (sortByName.checked) {
                var leftVal = left.name;
                var rightVal = right.name;
            } else {
                leftVal = left.team;
                rightVal = right.team;
            }
            return leftVal < rightVal ? -1 : 1;
        }
        delegate: Text {
            text: name + " (" + team + ")"
        }
    }

    ListView {
        anchors {
            left: parent.left
            top: controls.bottom
            right: parent.right
            bottom: parent.bottom
        }
        model: sortFilterModel
    }
}

Some Hints on Usage

As already pointed out: Do not use this approach for large lists of items. As sorting and filtering is done in QML/JavaScript, this could be a performance killer for your app.

Also note that with the SortFilterModel as it is implemented, you also get no “dynamic” filtering. When e.g. sorting or filtering criteria change, you have to manually call the update method.

Building Android Projects With Qt Creator And CMake

Sat, 04 Aug 2018 16:23:00 +0000

As a Qt developer, you most likely are using qmake as a build system for your apps. It comes bundles with Qt, is easy to use and usually gets the job done.

However, there are other alternatives out there, most notably cmake. What makes it interesting is, that there are a lot of projects (and in particular libraries) which use it, so if you go with cmake in your own app, you can easily pull in such libraries directly into your own build.

Now, cmake and Qt vastly play well together. However, if you target Android and you are using Qt Creator as your development vehicle, you have to tweak it a little bit. In this post, I show the steps you need to take to configure your Qt Creator IDE and your projects to be able to:

Build your Qt based Android app with Qt Creator.
Do the same from the command line, e.g. for CI/CD.
Deploy your app to a connected Android device and start it from with Qt Creator.

Let’s start.

Prerequisites

I will assume the following:

You have a working and recent Qt installation (e.g. 5.11.1, which is at the time of writing the most recent one).
You have a working Android SDK.
You have a working Android NDK, ideally version r10e.
You have a recent version of cmake, at least v3.7.
Qt Creator is readily set up, i.e. it finds the Qt installation as well as cmake, and the Android SDK and NDK.

Some words on the Android NDK requirement: r10e is a bit dated, yes. However, Qt itself currently is still compiled using it. Newer ones tend to cause issues, so you better stick with that specific release at least for building Qt apps. Currently, Qt is considering moving to clang as a compiler (which is by now the default one in the NDK). This switch will probably be released with Qt 5.12 (see this issue in the Qt bug tracker) - which probably also will mean you can use a more recent NDK release afterwards.

Step 1: Setting up Qt Kits in Qt Creator

If your environment is correctly set up, you should find Kit definitions for at least the installed Qt Android versions in the Kits section in the configuration dialog of Qt Creator:

These definitions work well when building apps using qmake, however, we have to fine-tune them to be really usable with cmake. Alternatively, you could provide the configurations needed in each app you build.

Start by selecting one of the Android kits, e.g the ARM one, and press the Clone button. We need to do this, because Qt Creator does not let us change the auto-detected kits. The cloned one should appear in the list of manually defined kits. Select it and scroll to the very bottom. There, you’ll find the cmake configuration:

Hit the Change button. This will bring up another dialog where you can provide variables that Qt Creator will pass down to cmake when configuring:

You will find some pre-defined variables here, most notably the C and C++ compilers to use (CMAKE_C_COMPILER and CMAKE_CXX_COMPILER), the path to the Qt installation (CMAKE_PREFIX_PATH) and the full path to the qmake executable (QT_QMAKE_EXECUTABLE).

We need to add some more variables to this list. Here’s the complete list of compiling to Android on ARM:

CMAKE_CXX_COMPILER:STRING=%{Compiler:Executable:Cxx}
CMAKE_C_COMPILER:STRING=%{Compiler:Executable:C}
CMAKE_PREFIX_PATH:STRING=%{Qt:QT_INSTALL_PREFIX}
QT_QMAKE_EXECUTABLE:STRING=%{Qt:qmakeExecutable}
CMAKE_SYSTEM_NAME=Android
CMAKE_SYSTEM_VERSION=16
CMAKE_ANDROID_ARCH_ABI=armeabi-v7a
CMAKE_ANDROID_STL_TYPE=gnustl_shared
ANDROID_SDK_ROOT=/opt/Android/android-sdk-linux/

For Android on x86, the list would look like this:

CMAKE_CXX_COMPILER:STRING=%{Compiler:Executable:Cxx}
CMAKE_C_COMPILER:STRING=%{Compiler:Executable:C}
CMAKE_PREFIX_PATH:STRING=%{Qt:QT_INSTALL_PREFIX}
QT_QMAKE_EXECUTABLE:STRING=%{Qt:qmakeExecutable}
CMAKE_SYSTEM_NAME=Android
CMAKE_SYSTEM_VERSION=16
CMAKE_ANDROID_ARCH_ABI=x86
CMAKE_ANDROID_STL_TYPE=gnustl_shared
ANDROID_SDK_ROOT=/opt/Android/android-sdk-linux/

What does the magic mean?

CMAKE_SYSTEM_NAME causes cmake to go to cross compiling mode, trying to configure and compile for Android.
CMAKE_SYSTEM_VERSION is the version of the target system to compile for. In case of Android, the version corresponds to the (minimum) Android SDK level we target.
CMAKE_ANDROID_ARCH_ABI tells cmake the Android ABI we want to compile to.
CMAKE_ANDROID_STL_TYPE specifies the variant of the STL to use.
Finally, via ANDROID_SDK_ROOT we point to the root of the Android SDK. This is not a standard cmake variable, We’ll use it later in our cmake files, as we need to pass this location to some Qt tools plus we need it ourselves for e.g. deploying our apps.

That’s it. To verify the configuration works as expected, create a minimal example like the below (which is basically generated via Qt Creator, selecting cmake as build system):

// main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

// main.qml
import QtQuick 2.11
import QtQuick.Controls 2.2
import QtQuick.Window 2.11

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    Label {
        text: qsTr("Android CMake Test")
        anchors.centerIn: parent
    }
}

<!-- qml.qrc -->
<RCC>
    <qresource prefix="/">
        <file>main.qml</file>
    </qresource>
</RCC>

# CMakeLists.txt
cmake_minimum_required(VERSION 3.1)

project(android-cmake-demo LANGUAGES CXX)

set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt5 COMPONENTS Core Quick REQUIRED)

add_executable(${PROJECT_NAME} "main.cpp" "qml.qrc")
target_compile_definitions(${PROJECT_NAME} PRIVATE $<$<OR:$<CONFIG:Debug>,$<CONFIG:RelWithDebInfo>>:QT_QML_DEBUG>)
target_link_libraries(${PROJECT_NAME} PRIVATE Qt5::Core Qt5::Quick)

Put these files together in one folder. You should be able to:

Load the CMakeLists.txt file in Qt Creator by using File and Open File or Project (unless you generated the project it right from Qt Creator - then, of course, it already is open).
Configure and compile the project at least for your host OS plus Android ARM and x86.

Step 2: Adjusting a Project’s CMakeFiles to Build For Android

When you build the sample app for your host OS, you should get the following:

So far, so good. However, without further ado we won’t be able to deploy out app to Android. This has two reasons:

In the CMakeLists.txt file above, we compile our app as executable. However, on Android, every app must have a Java entry point. Hence, we must provide such one as well. To better understand this, check out this Qt blog post.
The app needs to be packaged as APK.

To manage this, we first need to add two more files to the project:

# cmake/qt-android-mk-apk.cmake
include(CMakeParseArguments)

set(QT_ANDROID_MK_APK_DIR ${CMAKE_CURRENT_LIST_DIR})

function(qt_android_build_apk)
    set(options)
    set(oneValueArgs
        TARGET PACKAGE_NAME ANDROID_EXTRA_FILES QML_ROOT_PATH
        SDK_BUILD_TOOLS_VERSION EXTRA_LIBS)
    set(multiValueArgs)
    cmake_parse_arguments(
        APK "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})

    # Gather required variables to create the configuration file.

    find_package(Qt5 COMPONENTS Core REQUIRED)
    # Qt5Core_DIR now points to $Qt5InstallPrefix/lib/cmake/Qt5Core, so
    # we get the parent directory three times:
    get_filename_component(QT5_INSTALL_PREFIX "${Qt5Core_DIR}/../../.." ABSOLUTE)
    message("Qt5 installed in ${QT5_INSTALL_PREFIX}")

    # Adjust QML root path if not set:
    if(NOT APK_QML_ROOT_PATH)
        set(APK_QML_ROOT_PATH $<TARGET_FILE_DIR:${APK_TARGET}>)
    endif()

    # Get he toolchain prefix, i.e. the folder name within the
    # toolchains/ folder without the compiler version
    # APK_NDK_TOOLCHAIN_PREFIX
    file(RELATIVE_PATH APK_NDK_TOOLCHAIN_PREFIX ${CMAKE_ANDROID_NDK} ${CMAKE_CXX_COMPILER})
    string(REPLACE "/" ";" APK_NDK_TOOLCHAIN_PREFIX ${APK_NDK_TOOLCHAIN_PREFIX})
    list(GET APK_NDK_TOOLCHAIN_PREFIX 1 APK_NDK_TOOLCHAIN_PREFIX)
    string(LENGTH "-${CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION}" VERSION_LENGTH)
    string(LENGTH "${APK_NDK_TOOLCHAIN_PREFIX}" FOLDER_LENGTH)
    math(EXPR PREFIX_LENGTH ${FOLDER_LENGTH}-${VERSION_LENGTH})
    string(SUBSTRING "${APK_NDK_TOOLCHAIN_PREFIX}" 0 ${PREFIX_LENGTH} APK_NDK_TOOLCHAIN_PREFIX)

    # Get path to the target:
    set(APK_TARGET_OUTPUT_FILENAME $<TARGET_FILE:${APK_TARGET}>)

    # Get Android SDK build tools version:
    if(NOT APK_SDK_BUILD_TOOLS_VERSION)
        file(GLOB sdk_versions RELATIVE ${ANDROID_SDK_ROOT}/build-tools
            ${ANDROID_SDK_ROOT}/build-tools/*)
        list(GET sdk_versions -1 APK_SDK_BUILD_TOOLS_VERSION)
    endif()

    # Step 1: Create an intermediate config file. At this point,
    # the generator expressions will we use are not yet resolved.
    configure_file(
        ${QT_ANDROID_MK_APK_DIR}/qt-android-deployment.json.in
        ${CMAKE_CURRENT_BINARY_DIR}/${APK_TARGET}-config.json.pre)

    # Step 2: Run file(CONFIGURE ...) to create the final config JSON
    # with generator expressions resolved:
    file(
        GENERATE
        OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${APK_TARGET}-config.json
        INPUT ${CMAKE_CURRENT_BINARY_DIR}/${APK_TARGET}-config.json.pre)

    # Step 3: Create a custom target which will build our APK:
    set(APK_DIR ${CMAKE_CURRENT_BINARY_DIR}/${APK_TARGET}-apk-build)
    if(NOT APK_ANDROID_EXTRA_FILES)
        set(
            APK_ANDROID_EXTRA_FILES
            ${QT5_INSTALL_PREFIX}/src/android/templates/)
    endif()
    if(JAVA_HOME)
        set(ANDROIDDEPLOYQT_EXTRA_ARGS
            ${ANDROIDDEPLOYQT_EXTRA_ARGS} --jdk '${JAVA_HOME}')
    endif()
    if(${CMAKE_BUILD_TYPE} STREQUAL Release)
        set(ANDROIDDEPLOYQT_EXTRA_ARGS
            ${ANDROIDDEPLOYQT_EXTRA_ARGS} --release)
        set(APK_FILENAME ${APK_TARGET}-apk-build-release-unsigned.apk)
    else()
        set(APK_FILENAME ${APK_TARGET}-apk-build-debug.apk)
    endif()
    add_custom_target(
        ${APK_TARGET}-apk
        COMMAND ${CMAKE_COMMAND} -E remove_directory ${APK_DIR}
        COMMAND ${CMAKE_COMMAND} -E copy_directory
            ${QT5_INSTALL_PREFIX}/src/android/templates/
            ${APK_DIR}
        COMMAND ${CMAKE_COMMAND} -E copy_directory
            ${APK_ANDROID_EXTRA_FILES}/
            ${APK_DIR}
        COMMAND ${CMAKE_COMMAND} -E make_directory
            ${APK_DIR}/libs/${CMAKE_ANDROID_ARCH_ABI}
        COMMAND ${CMAKE_COMMAND} -E copy
            ${APK_TARGET_OUTPUT_FILENAME}
            ${APK_DIR}/libs/${CMAKE_ANDROID_ARCH_ABI}
        COMMAND ${QT5_INSTALL_PREFIX}/bin/androiddeployqt
            --verbose
            --output ${APK_DIR}
            --input ${CMAKE_CURRENT_BINARY_DIR}/${APK_TARGET}-config.json
            --deployment bundled
            --gradle
            ${ANDROIDDEPLOYQT_EXTRA_ARGS}
    )

    # Step 4: Create a custom target which pushes the created APK onto
    # the device.
    add_custom_target(
        ${APK_TARGET}-apk-install
        COMMAND ${ANDROID_SDK_ROOT}/platform-tools/adb install -r
            ${APK_DIR}/build/outputs/apk/${APK_FILENAME}
        DEPENDS
            ${APK_TARGET}-apk
    )

endfunction()

… and …

 // cmake/qt-android-deployment.json.in
{
 "description": "This file is read by androiddeployqt",
 "qt": "@QT5_INSTALL_PREFIX@",
 "sdk": "@ANDROID_SDK_ROOT@",
 "ndk": "@CMAKE_ANDROID_NDK@",
 "toolchain-prefix": "@APK_NDK_TOOLCHAIN_PREFIX@",
 "tool-prefix": "@CMAKE_CXX_ANDROID_TOOLCHAIN_MACHINE@",
 "toolchain-version": "@CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION@",
 "ndk-host": "@CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG@",
 "target-architecture": "@CMAKE_ANDROID_ARCH_ABI@",
 "application-binary": "@APK_TARGET_OUTPUT_FILENAME@",
 "android-package": "@APK_PACKAGE_NAME@",
 "qml-root-path": "@APK_QML_ROOT_PATH@",
 "sdkBuildToolsRevision": "@APK_SDK_BUILD_TOOLS_VERSION@",
 "android-package-source-directory": "@APK_ANDROID_EXTRA_FILES@",
 "android-extra-libs": "@APK_EXTRA_LIBS@"
}

We will pull in the first file into our CMakeLists.txt. It provides a function - qt_android_build_apk - which we can use to wrap our app and create an APK file. This function also will create a target to deploy the app to a connected Android device. The second file is a template for a JSON deployment configuration. This configuration will later be passed to the androiddeployqt tool, which copies the dependencies of our app into the APK build folder.

With these two, we can adjust our CMakeLists.txt file as follows:

cmake_minimum_required(VERSION 3.1)

project(android-cmake-demo LANGUAGES CXX)

set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt5 COMPONENTS Core Quick REQUIRED)

include(cmake/qt-android-mk-apk.cmake)

if(ANDROID)
    add_library(${PROJECT_NAME} SHARED "main.cpp" "qml.qrc")
else()
    add_executable(${PROJECT_NAME} "main.cpp" "qml.qrc")
endif()
target_compile_definitions(${PROJECT_NAME} PRIVATE $<$<OR:$<CONFIG:Debug>,$<CONFIG:RelWithDebInfo>>:QT_QML_DEBUG>)
target_link_libraries(${PROJECT_NAME} PRIVATE Qt5::Core Qt5::Quick)

qt_android_build_apk(
    TARGET ${PROJECT_NAME}
    PACKAGE_NAME org.example.QmlCmakeDemo
    QML_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}
    ANDROID_EXTRA_FILES ${CMAKE_CURRENT_SOURCE_DIR}/android
)

The notable changes:

Via include(), we pull in the utility file from above into the build system.
Via if(ANDROID), we check if we are building for Android. If this is the case, we use add_library instead of add_executable to build a shared library instead of an executable file.
At the very end, we use our qt_android_build_apk function.

The last point is the most important one. It will cause the build to create the deployment JSON file required to use androiddeployqt. In addition, it will add two new targets to the build: android-cmake-demo-apk will cause our app to be packaged into an APK file. If we are doing a debug build, the resulting APK will be signed with a debug key, so you can immediately deploy it to a device. For release builds, the APK will not be signed. You can, however, adjust the function to do exactly this, if you need. The second target - android-cmake-demo-akp-install - causes the APK to get deployed to an Android device connected to our host (or a running Android Virtual Device).

The qt_android_build_apk takes several options to customize its behavior:

TARGET is the application we want to generate an APK for. Hence, if you have a larger project with several apps, you can call the function several times, once for each app you want to package.
PACKAGE_NAME is the name of the package (e.g. org.example.AndroidCmakeDemo) used to identify the app on Android. This usually should be the same as mentioned in the Android Manifest file used for the build (see below).
ANDROID_EXTRA_FILES is the path to a directory containing extra files to use for the Android APK build. This usually should be at least the file AndroidManifest.xml. However, you can also add other files. A template for a complete folder including Java sources for the main activity class can be found in the Qt installation (e.g. $HOME/Qt/5.11.1/android_armv7/src/android/templates/). In the example above, we use the android subdirectory as source for these files.
QML_ROOT_PATH is the path to the app’s QML files. This is required to include all dependencies of the app.
EXTRA_LIBS is a (comma separated) list of additional library files which shall be included in the APK and loaded as soon as the app starts. This is useful if your app links against additional libraries or needs them at runtime (e.g. OpenSSL - in case you need HTTPS support).

Note: If you encounter any issues during the APK build, make sure you include a custom AndroidManifest.xml and set the target properties right, e.g. minimal and target SDK versions, the application name and so on.

Step 3: Building And Running The APK From Within Qt Creator

With the above changes, we add the basic tools into our app’s build to create an APK. We can make use of these additional build steps to comfortably build and run our APKs from within Qt Creator.

First, head over to the Projects tab, where you can manage the enabled kits for the open project. For each kit, you can configure settings for building and running. Switch to the Run area for the Android kit you wish to build and run an APK for. The first thing here is to disable the default deployment step by clicking once on the disable button at the top of the Deploy Configurations box:

If you don’t do this, deployment will fail, as this step only works properly when using qmake. Next, we need to add add a custom build step to the deployment. In this step, we select the app-name-apk-install target, which will cause the APK to be build and deployed to a connected Android (virtual) device:

Finally, we tweak the run settings:

We need to select Custom Executable. As executable, we select the adb tool located in our Android SDK installation, i.e. in my case this is /home/martin/Android/android-sdk-linux/platform-tools/adb. In the field Command line arguments, we use something like:

shell am start -n org.example.QmlCmakeDemo/org.qtproject.qt5.android.bindings.QtActivity

The shell am start part tells adb to run an installed app on the connected device. Via -n $PACKAGE_NAME/$ACTIVITY_NAME, we tell it which one. You find both strings in the Android Manifest file.

When everything is set up correctly, you should not be able to create and run your app right from Qt Creator 😉

Step 4: Building Your APK From The Command Line

Being able to build and run your APK from within Qt Creator is nice. However, you also want to be able to do the same from the command line (e.g. to enable CI/CD for your project). This is quite easy, we basically just need to take the variables we set in Qt Creator and also pass them to cmake when configuring our project. Here’s a minimal shell script which does so for ARM targets:

# Set up some variables to shorten stuff later on:
export ANDROID_SDK=$HOME/Android/android-sdk-linux
export ANDROID_NDK=$HOME/Android/android-ndk-r10e
export QT_ROOT=$HOME/Qt/5.11.1/android_armv7

cd path/to/your/project
mkdir build
cd build
cmake \
    -DANDROID_SDK_ROOT=$ANDROID_SDK \
    -DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \
    -DCMAKE_ANDROID_STL_TYPE=gnustl_shared \
    -DCMAKE_CXX_COMPILER=$NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin/arm-linux-androideabi-g++ \
    -DCMAKE_C_COMPILER:STRING=$NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin/arm-linux-androideabi-gcc \
    -DCMAKE_PREFIX_PATH=$QT_ROOT \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=16 \
    -DQT_QMAKE_EXECUTABLE=$QT_ROOT/bin/qmake \
    ..
cmake --build .

# Build APK for your app, e.g. to package our demo:
cmake --build . android-cmake-demo-apk

# And to run it, just use the install target:
cmake --build . android-cmake-demo-apk-install

Using FontAwesome 5 in QML

Fri, 30 Mar 2018 18:57:00 +0000

FontAwesome is a set of icon fonts making it easy to beef up your user interfaces. It is mostly used in web applications (aka HTML/CSS), however, leveraging it to your Qt applications is not difficult either.

First, download the latest Desktop release from their website. You unzip it and find the contained *.otf files in otfs folder. You should have the following files there:

Font Awesome 5 Brands-Regular-400.otf
Font Awesome 5 Free-Regular-400.otf
Font Awesome 5 Free-Solid-900.otf

Copy these into your application’s source directory.

Note: Make sure you use a recent version of FontAwesome 5. Earlier releases had an issue which prevented you to use both the solid and regular variants. This issue is meanwhile gone for the OTF files. Also, you still will encounter the issue when using the TTF files, but as Qt/QML can deal with both, just make sure you pick the OTF version from the Desktop release.

In QML, we can now easily access these fonts by writing a (singleton) component which makes them available:

// Fonts.qml

pragma Singleton

import QtQuick 2.0

Item {
    id: fonts

    readonly property FontLoader fontAwesomeRegular: FontLoader {
        source: "./Font Awesome 5 Free-Regular-400.otf"
    }
    readonly property FontLoader fontAwesomeSolid: FontLoader {
        source: "./Font Awesome 5 Free-Solid-900.otf"
    }
    readonly property FontLoader fontAwesomeBrands: FontLoader {
        source: "./Font Awesome 5 Brands-Regular-400.otf"
    }

    readonly property string icons: fonts.fontAwesomeRegular.name
    readonly property string brands: fonts.fontAwesomeBrands.name
}

For the singleton to work, you must create a qmldir file next to it as well:

// qmldir
singleton Fonts 1.0 Fonts.qml

With this, you should be able to display some icons using e.g. a ToolButton:

// FontAwesomeToolButton.qml

import QtQuick 2.9
import QtQuick.Controls 2.2

// This must point to the directory where you placed
// the 'Fonts.qml' file. If all your sources are in the
// same directory, this can be '.' as well.
import "../path/to/Fonts"

ToolButton {
    id: button

    property alias symbol: button.text

    // This can be set to either Fonts.icons or Fonts.brands
    // to switch between the two icon sets.
    font.family: Fonts.solidIcons

    // This controls the style of the regular icons which is
    // used. The default value (Regular) will map to the regular
    // icon set. Use either Font.Bold or Font.Light to switch
    // to the other styles.
    font.weight: Font.Regular
}

And finally we can use our tool button implementation:

// demo.qml

import QtQuick 2.9

// Adjust the paths accordingly. The latter import is where
// our tool button implementation is stored:
import "./path/to/Fonts"
import "./path/to/Components"

Grid {
    columns: 3

    FontAwesomeToolButton {
        symbol: "\uf2bb"
    }
    FontAwesomeToolButton {
        symbol: "\uf556"
    }
    FontAwesomeToolButton {
        symbol: "\uf35b"
    }
    FontAwesomeToolButton {
        symbol: "\uf2bb"
        font.weight: Font.Bold
    }
    FontAwesomeToolButton {
        symbol: "\uf556"
        font.weight: Font.Bold
    }
    FontAwesomeToolButton {
        symbol: "\uf35b"
        font.weight: Font.Bold
    }
    FontAwesomeToolButton {
        symbol: "\uf270"
    }
    FontAwesomeToolButton {
        symbol: "\uf294"
    }
    FontAwesomeToolButton {
        symbol: "\uf268"
    }
}

Run this e.g. via qmlscene:

qmlscene ./demo.qml

You should get something like this:

While this approach works, you will have notices one bad thing: In order to select which icon to display, we inserted the unicode character codes as label names. You can get them easily from the FontAwesome Gallery, however, after inserting into the QML source code you do not quickly see which icon a code refers to. In HTML, you would use something like

<i class="fas fa-anchor"></i>
<i class="fas fa-angle-double-right"></i>
<i class="fas fa-asterisk"></i>

which is far more readable. To achieve something similar in QML, we can extract some meta information from the FontAwesome download package and generate another QML component from that one.

First, create a file fa_iconsjson2qml.py and put the following content in it:

#!/bin/env python3

"""
Convert FontAwesome's `icons.json` to QML.

This script creates a QML component which defines
constants for all FontAwesome icons listed in the file
`icons.json` in the FontAwesome package.
"""

import sys


def _dash2cap(name):
    try:
        while True:
            idx = name.index("-")
            pre = name[0:idx]
            suf = name[idx + 2:]
            cap = name[idx + 1:idx + 2].capitalize()
            name = pre + cap + suf
    except ValueError:
        pass
    return name


def _main(argv):
    import json
    if len(argv) != 3:
        print("Usage:")
        msg = "    {} path/to/icons.json path/to/Icons.qml"
        msg = msg.format(argv[0])
        print(msg)
        sys.exit(1)
    with open(argv[1], "r") as file:
        icons = json.load(file)
    lines = []
    lines.append("pragma Singleton")
    lines.append("import QtQuick 2.0")
    lines.append("")
    lines.append("QtObject {")
    prop = '    readonly property string {}: "{}"'
    for key in icons:
        name = "fa-" + key
        name = _dash2cap(name)
        code = "\\u" + icons[key]["unicode"]
        line = prop.format(name, code)
        lines.append(line)
    lines.append("}")
    with open(argv[2], "w") as file:
        file.write("\n".join(lines))


if __name__ == '__main__':
    _main(sys.argv)

Make the file executable and call it on the file icons.json which is contained in the FontAwesome zip:

chmod +x ./fa_iconsjson2qml.py
./fa_iconsjson2qml.py \
    ./path/to/FontAwesome/metadata/icons.json \
    ./path/to/qml/sources/Fonts/Icons.qml

This script basically extracts the available icons from the JSON file and creates another QML singleton component which looks like this:

pragma Singleton
import QtQuick 2.0

QtObject {
    readonly property string fa500px: "\uf26e"
    readonly property string faAccessibleIcon: "\uf368"
    readonly property string faAccusoft: "\uf369"
    readonly property string faAddressBook: "\uf2b9"
    readonly property string faAddressCard: "\uf2bb"
    // several hundred similar lines following...
}

Ideally, put the file next to the Fonts.qml file and edit the qmldir file to look like this:

singleton Icons 1.0 Icons.qml
singleton Fonts 1.0 Fonts.qml

Now, you can modify the demo from above to:

// demo.qml

import QtQuick 2.9

// Adjust the paths accordingly. The latter import is where
// our tool button implementation is stored:
import "./path/to/Fonts"
import "./path/to/Components"

Grid {
    columns: 3

    FontAwesomeToolButton {
        symbol: Icons.faAddressCard
    }
    FontAwesomeToolButton {
        symbol: Icons.faAngry
    }
    FontAwesomeToolButton {
        symbol: Icons.faArrowAltCircleUp
    }
    FontAwesomeToolButton {
        symbol: Icons.faAddressCard
        font.weight: Font.Bold
    }
    FontAwesomeToolButton {
        symbol: Icons.faAngry
        font.weight: Font.Bold
    }
    FontAwesomeToolButton {
        symbol: Icons.faArrowAltCircleUp
        font.weight: Font.Bold
    }
    FontAwesomeToolButton {
        symbol: Icons.faAmazon
    }
    FontAwesomeToolButton {
        symbol: Icons.faBluetoothB
    }
    FontAwesomeToolButton {
        symbol: Icons.faChrome
    }
}

… which is way more readable.

Qt Quick Controls 2: Automatically Set The Width of Menus

Tue, 13 Mar 2018 19:44:00 +0000

The Qt Quick Controls 2 module which Qt has introduced some time ago gets better and better with every release. With the new Fusion style it not finally gets interesting enough also for Desktop applications (even though the other styles - like the Material one - also look very appealing on non-mobiles).

However, there are still some rough corners reminding us on the rather mobile heritage of QQC2:

I recently migrated an app to the new component library. The app uses the built-in MenuBar to display a menu bar. There is also a native MenuBar available, however, that one was not a choice for the app in question.

In that app’s menu, I had to use very long menu item names. In this case, file names in a recent files menu. The point is, QQC2 basically just truncates these.

Consider the following QML code:

// main.qml
import QtQuick 2.10
import QtQuick.Window 2.10
import QtQuick.Controls 2.3

ApplicationWindow {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    menuBar: MenuBar {
        Menu {
            title: qsTr("Normal Menu")

            MenuItem {
                text: qsTr("This is a menu item with a long title")
            }

            MenuItem {
                text: qsTr("And here is just another one with an even longer one")
            }
        }
    }
}

This basically will lead to the following:

As you can see, the menu item entries get truncated at the end. To prevent this, we could simple set the width of the Menu to some larger value, but: What would be the right width? We could experiment so it looks good with the current theme, font size and resolution, but that’s going to break rather quickly, especially if you plan to translate the user interface strings.

Hence, a better approach might be to automatically set the width of the menu depending on the largest item in it. For this, we just create a new component called AutoSizingMenu:

// AutoSizingMenu.qml
import QtQuick 2.10
import QtQuick.Controls 2.3

Menu {
    width: {
        var result = 0;
        var padding = 0;
        for (var i = 0; i < count; ++i) {
            var item = itemAt(i);
            result = Math.max(item.contentItem.implicitWidth, result);
            padding = Math.max(item.padding, padding);
        }
        return result + padding * 2;
    }
}

And rewrite our main window class to:

// main.qml
import QtQuick 2.10
import QtQuick.Window 2.10
import QtQuick.Controls 2.3

ApplicationWindow {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    menuBar: MenuBar {
        AutoSizingMenu {
            title: qsTr("Normal Menu")

            MenuItem {
                text: qsTr("This is a menu item with a long title")
            }

            MenuItem {
                text: qsTr("And here is just another one with an even longer one")
            }
        }
    }
}

And voila, here we go:

So what we do is basically this:

We bind the width property of the menu to a value we calculate by iterating over all child menu items.
For each menu item, we take the implicitWidth of the contentItem and the padding of the item itself. The content item is responsible for rendering the text of the menu entry.
The desired width of the menu is the sum of the maximum width and the maximum padding values of all entries.

There are probably some things to consider using this approach:

Such complex property bindings are expensive. However, granted that most menus have only a limited number of entries which rarely change, this should be fine.
An alternative to increasing the width could also be to use a custom contentItem in the affected menu entries and let the text wrap (instead of being ellided). I tried this in the app I ported and it worked well for most menu items, however, in particular for the ones with the very long file names as texts, it did not work. This could have been due to these menu’s were populated via a Repeater - so if you do not use such an approach to populate your menu items, the wrapping approach might be better (as you require less horizontal space).
Last but not least, the above sample component does ensure the menu fits into the window. If the largest menu item is too wide, the menu will appear cut off at the window edge.

Prevent qmake from installing test cases

Sat, 10 Jun 2017 00:00:00 +0000

If you use qmake to build your Qt based projects and at the same time the QtTest framework to write unit tests, you might have run into a strange behavior:

Generated Makefiles have an installs feature, which mainly is used on Unix like operating systems to install a previously compiled project. Normally you would expect the installs feature only puts your libraries and executable files into the target location. However, unit tests also get installed by default - which, usually, is not what’s wanted, right?

Fortunately, it’s quite easy to tell qmake not to install unit tests by default, simply add the no_testcase_installs configuration switch to your unit test’s .pro file:

TARGET   = my_unit_test
CONFIG  += console testcase no_testcase_installs
QT      += testlib
# ...

That should already do the trick ;-)

Creating config header files using qmake

Wed, 10 May 2017 00:00:00 +0000

In case you are using qmake as tool to build your Qt based application, you might sometimes jealously look over to other build systems like cmake for their support of configuration header files (or more generally “configuration” files at all, as this is not limited to C/C++ headers in the end). So what’s the background? There are several files where you need the content to reflect something that is usually only known to the build system. This could be

Information about (optional) build dependencies of your app or library.
User provided configuration options, e.g. installation target locations for use with make install.

In a lot of cases you just might get away by passing certain stuff through to the compile process as defines (using qmake’s DEFINES variable). However, there are cases where this is not the case. Probably the most prominent example would be .desktop files in Linux, where the file needs to point to the installation location of your application. However, you even will find situations where using DEFINES is not sufficient (admittedly, this is when stretching qmake’s capabilities a bit, but hey…).

In these cases, what you actually want to create is configured files on disk, which are fed into further steps of the build or installation process later on. Long story short: While other tools have their way to create such files well documented, qmake is hiding this a bit (at least I was not able to find information about it in the official docs). But nevertheless, such a function exists: Enter, QMAKE_SUBSTITUTES!

QMAKE_SUBSTITUTES is a variable you can append to template files (e.g. config.h.in, MyCoolApp.desktop.in), that are stored in your source directory. qmake will configure these files and write the result to appropriate files without the *.in suffix into the build directory. Configuring in this case means that any references of the form $$SOME_VARIABLE will be replaced by the respective content of that variable known to qmake. A very simple example: You could use this to create a header file containing the version number of your app. In your project files, you would have something like this:

# ...
VERSION = 1.2.3
QMAKE_SUBSTITUTES += config.h.in
# ...

The content of the config.h.in file could look like this:

#ifndef MYAPP_CONFIG_H
#define MYAPP_CONFIG_H

#define MYAPP_VERSION '"$$VERSION"'

#endif // MYAPP_CONFIG_H

And finally, you could pull in this file into your source and header files as required:

#include 

#include "config.h"

int main(int argc, char** argv) {
    std::cout << "MyApp version " << MYAPP_VERSION << std::endl;
    return 0;
}

Setting up suspend to hibernate in Fedora

Tue, 28 Feb 2017 00:00:00 +0000

Important Note: When you upgrade to the current version Fedora 26 (which right now - July 2017 - ships with systemd 233), you might run into a regression which prevents any units depending on the suspend one not to be executed. The same applies to any scripts and programs in /usr/lib/systemd/system-sleep/ which are supposed to be executed before and after one of the power save states is activates. As a consequence, suspend-to-hibernate is not working on Fedora as long as this issue is not fixed in upstream systemd and rolled out to Fedora :-(

Computers usually support two major energy saving modes: Suspend and Hibernate. Suspend basically shuts down all hardware components except your RAM (because it will preserve your current state there). Hibernate instead will write the current RAM contents to disk and then turn off everything. Both modes have their pro’s and con’s: Suspend is much faster, i.e. when you close your laptop lid you usually want the session to be back as soon as you open the lid again. So during the day you probably want to use this mode mostly. Hibernate on the other side has a greater potential for saving energy, as the system is basically shut down completely and restored to exactly this point later when you turn it on again. Hence, this mode is ideal when you seldom use your device (e.g. when you have to prepare for some events in your professional life and hence don’t have too much free time to spend with your private hardware ;-) ). Besides the energy and time components, there is another point that kicks in when using full disk encryption: Using suspend is less secure, because sensitive data is stored unencrypted in the still powered on RAM. Especially when you often take your laptop with you or in case of a laptop you use for your company, you surely don’t want someone else to gain access to your data. The good news is: You actually don’t have to decide for one or the other ;-) While it is not available out of the box, you can easily enable a mode where your laptop goes into suspend mode when you close your lid and later - say after one or two hours of not being used - it goes to hibernate, increasing energy saving and protecting your data in case you use full disk encryption. So, here is how to enable this “suspend-to-hibernate” mode in Fedora:

Enable Hibernate

You read right. If you have not already done so, you first have to enable Hibernate on your freshly installed Fedora box. This is due to the installer does not add the required parameters to the kernel boot arguments. Fortunately, this is a well documented task to do.

Enable Suspend-to-Hibernate

This as well is quite easy, even though not documented for the case of Fedora. However, our friends over at Arch Linux have summed up everything nicely in their Wiki and Forums: First, you need to create a new file /etc/systemd/system/suspend-to-hibernate.service with the following contents:

[Unit]
Description=Delayed hibernation trigger
Documentation=https://bbs.archlinux.org/viewtopic.php?pid=1420279#p1420279
Documentation=https://wiki.archlinux.org/index.php/Power_management
Before=suspend.target
Conflicts=hibernate.target hybrid-suspend.target
StopWhenUnneeded=true

[Service]
Type=oneshot
RemainAfterExit=yes
Environment="WAKEALARM=/sys/class/rtc/rtc0/wakealarm"

# Important: Here you can set the delay after when we go to hibernate:
Environment="SLEEPLENGTH=+2hour"

ExecStart=-/usr/bin/sh -c 'echo -n "alarm set for "; date +%%s -d$SLEEPLENGTH | tee $WAKEALARM'
ExecStop=-/usr/bin/sh -c '\
  alarm=$(cat $WAKEALARM); \
  now=$(date +%%s); \
  if \[ -z "$alarm" \] || \[ "$now" -ge "$alarm" \]; then \
     echo "hibernate triggered"; \
     systemctl hibernate; \
  else \
     echo "normal wakeup"; \
  fi; \
  echo 0 > $WAKEALARM; \
'

[Install]
WantedBy=sleep.target

Basically, you can ignore most stuff if you don’t care. The most interesting part is the line after the Important: comment: It determines the time the computer shall remain in suspend before going to hibernate. The default two hours are a decent choice for most use cases. In theory, you could try to enable this new service by running

sudo systemctl enable suspend-to-hibernate

However, some updates in systemd obviously changed something that prevents the service from working flawlessly with the suspend service delivered with systemd itself. The good thing is, that this is easily fixed. Run the following

sudo cp /usr/lib/systemd/system/suspend.target /etc/systemd/system/

To create a local copy of the suspend target definition and edit it to include the part after the line marked with Important: below (keep everything else as it is to be as near at the default definition as possible):

#  SPDX-License-Identifier: LGPL-2.1+
#
#  This file is part of systemd.
#
#  systemd is free software; you can redistribute it and/or modify it
#  under the terms of the GNU Lesser General Public License as published by
#  the Free Software Foundation; either version 2.1 of the License, or
#  (at your option) any later version.

[Unit]
Description=Suspend
Documentation=man:systemd.special(7)
DefaultDependencies=no
Requires=systemd-suspend.service
After=systemd-suspend.service
StopWhenUnneeded=yes

# Important: Add a dependency to our suspend-to-hibernate service:
Requires=suspend-to-hibernate.service

That’s it. If you’ve not already done so enable the suspend-to-hibernate service as shown above using systemctl enable.