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 gets updates from the open source community using GitHub pull requests.

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 occasionally long review process in the upstream git repository 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
}

Using Commercial Qt

By default, the meta-qt5 recipes configure Qt using Open Source licensing. Users with valid commercial license can change this, so that Qt is configured with commercial licensing enabled. This can be done with QT_EDITION variable in conf/local.conf or similar global configuration file:

QT_EDITION = "commercial"

Using Qt 5.15 LTS Commercial Releases

Qt 5.15 LTS (Long Term Support) is a commercial only release and you will need a commercial license. Qt 5.15.3 is the first LTS release. See the Change Log for more information about versions.

In order to build Qt 5.15 LTS Commercial in Yocto, you will need to have completed the following steps first:

• Set up Qt Gerrit as per the instructions at Setting up Gerrit.
• Clone the code at yocto/meta-qt5.git instead of the one at github.

Now you can build Qt in Yocto as before the switch to LTS.

Using https protocol for Qt code checkouts

By default, meta-qt5 will use ssh access to fetch the Qt source code for the LTS releases. If you are unable to use ssh protocol, you can switch the git protocol to HTTPS by configuring it in your build environment:

QT_LTS_GIT_PROTOCOL = "https"

Make sure that you have set up Gerrit and ensure that your local build machine is set up for https access.

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.

Building Your Own Qt Application

You can build your own Qt application with meta-qt5 by inheriting the correct class to your application recipe. After setting the usual SRC_URI, DEPENDS and other common bitbake variables, use qmake5 if you have a qmake project:

inherit qmake5

or cmake_qt5 if you have a cmake project using Qt:

inherit cmake_qt5

In case you need to give qmake additional arguments, you can use the EXTRA_QMAKEVARS_PRE variable:

EXTRA_QMAKEVARS_PRE += "CONFIG+=extra-args"