meta-qt5 is a Yocto compatible meta layer that provides recipes for Qt modules. This topic provides common guidelines how you can use meta-qt5. For more detailed information about Yocto Project, see Yocto Project Documentation.

meta-qt5 in GitHub and Gerrit

The upstream meta-qt5 Repository in GitHub is the official meta-qt5 version. It get updates via patch requests that are made in the openembedded-devel mailing list (see OpenEmbedded Mailing Lists).

Also, Qt Gerrit provides a version of the meta-qt5 Git repository. It is a mirror of the upstream GitHub version. You should use yocto/meta-qt5.git when you need to check out the meta-qt5 mirror.

Qt for Device Creation uses the meta-qt5 in Qt Gerrit as it always contains the latest Qt version. The long review process in the upstream mailing list causes delay in approving fixes and updates. Thus it is unpractical to utilize it in the Qt release process.

All changes in the Gerrit mirror are contributed back to the upstream meta-qt5. Usually, this is done when a new Qt version is released.

Using meta-qt5

You need to include the meta-qt5 layer into your Yocto build environment. Typically, this means editing the conf/bblayers.conf file in order to include a path for meta-qt5. Then you can include any Qt module into your image or toolchain.

Configuring Qt modules

meta-qt5 provides recipes for each Qt module. Most recipes support PACKAGECONFIG options that you can use to modify features each Qt module is built with.

By default, meta-qt5 enables only a minimal set of features that is available in a Qt module. Depending on your feature needs, most likely you need to modify at least options for QtBase.

For example, in order to modify QtBase options to enable OpenGL ES2 support, you need to create a qtbase_git.bbappend file and add the PACKAGECONFIG option as follows:

PACKAGECONFIG += "gles2"

Providing Hardware Specific Options

Depending on your target hardware, you may need to provide additional compile arguments to be able to build Qt as required. The default mkspec that is used in the Yocto build includes additional file mkspecs/oe-device-extra.pri that you can use to provide configurations for Qt builds.

The following example demonstrates how you can use qtbase_git.bbappend to add additional arguments that are required for building Qt with OpenGL support:

do_configure_prepend() {
    cat > ${S}/mkspecs/oe-device-extra.pri <<EOF
    QMAKE_LIBS_EGL += -lEGL -ldl -lglib-2.0 -lpthread
    QMAKE_LIBS_OPENGL_ES2 += -lGLESv2 -lgsl -lEGL -ldl -lglib-2.0 -lpthread

    QMAKE_CFLAGS += -DLINUX=1 -DWL_EGL_PLATFORM
    QMAKE_CXXFLAGS += -DLINUX=1 -DWL_EGL_PLATFORM

    QT_QPA_DEFAULT_PLATFORM = eglfs
    EOF
}

Note: The flags in the example code are specific to one particular device. In general, the used flags depend on your target device.

Using Static Qt Version in Boot to Qt Images

By default, meta-qt5 builds Qt5 as a set of dynamic libraries. If needed, you can change the Qt configuration so that static libraries are produced instead. Then your application is linked against the Qt5 static libraries and you can produce a single binary without additional dependencies to Qt libraries. You can enable a static build by adding a new option qt5-static into the DISTRO_FEATURES variable.

Because each Qt application includes all the required Qt libraries, builds can become overly large if you enable tests and examples for Qt modules. For this reason, you should disable the options ptest from DISTRO_FEATURES and tests from PACKAGECONFIG in QtBase's recipe. This ensures that tests are not built for the Qt modules.

If you build a QML application statically, you need to add qtdeclarative-native as a dependency to your application's recipe. Other changes are not required.