meta-qt6 is a meta layer for OpenEmbedded and Yocto that provides recipes for Qt modules and support for building your application using Qt. This topic provides common guidelines how you can use meta-qt6. For more detailed information about Yocto Project, see Yocto Project Documentation.

Accessing and contributing to meta-qt6

The meta-qt6 layer is available with MIT license and is under Qt Gerrit with git mirror available in code.qt.io. Contributions are welcome using the Qt Code Review in similar fashion as contributions to the Qt code. Qt Gerrit works nicely for code review and it also lets us utilize the Qt CI system for build verification before commits are merged. Bugs and other issues can be reported and discussed in Qt Bug Tracker using component Yocto: meta-qt6 layer

Using meta-qt6

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

Configuring Qt modules

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

A reasonable default set of features is already enabled in meta-qt6 for each Qt module that has PACKAGECONFIG options, but depending on your feature needs, you can modify the configuration for each Qt module separately.

For example, if you want to enable all the examples in QtBase, you need to create a qtbase_git.bbappend file and add the PACKAGECONFIG option as follows:

PACKAGECONFIG += "examples"

Using Commercial Qt

By default, the meta-qt6 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 Commercial Qt Add-ons

Some of the Qt add-on modules are commercial-only requiring a commercial license. These modules are not included in the default meta-toolchain-qt6 and packagegroup recipes unless variable QT_COMMERCIAL_MODULES=1 is set. QT_EDITION must also be set to commercial to enable the add-on modules.

To access the source code and build these add-ons, you must set up Qt Gerrit as per instructions at Setting up Gerrit.

Using Qt 6.2 LTS Commercial Releases

Qt 6.2 LTS (Long-term Support) is a commercial-only release requiring a commercial license. Qt 6.2.5 was the first commercial LTS release. See the change log for more information about versions.

To build Qt 6.2 LTS Commercial in Yocto, the following steps need to be completed first:

• Set up Qt Gerrit as per instructions at {Setting up Gerrit}.
• Check out the correct LTS branch on yocto/meta-qt6 git repository. The LTS releases are available in branches named lts-6.x.

Then, proceed to build Qt in Yocto as before.

Using https protocol for Qt code checkouts

By default, meta-qt6 uses ssh to fetch the Qt source code for LTS releases. If you're unable to use the ssh/git protocol, switch to use https by configuring it in your build environment:

QT_COMMERCIAL_GIT_PROTOCOL = "https"

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

Building Static Version of Qt

By default, meta-qt6 builds Qt as a set of dynamic libraries. If needed, you can change the Qt configuration so that static libraries are produced instead. Your application is then linked against the static libraries and you can produce a single binary without additional dependencies to Qt libraries. You can enable a static Qt build by adding it into the qtbase's PACKAGECONFIG.

PACKAGECONFIG += "static"

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 and examples from PACKAGECONFIG in Qt module recipes. This ensures that tests and examples are not built for the Qt modules.

For building your application statically, see Linking to Static Builds of Qt

Building Your Own Qt Application

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

inherit qt6-qmake

or qt6-cmake if you have a CMake project using Qt:

inherit qt6-cmake

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

EXTRA_QMAKEVARS_PRE += "CONFIG+=extra-args"

For CMake builds, you can use the EXTRA_OECMAKE variable

EXTRA_OECMAKE += "-DFEATURE_EXTRA=ON"

Toolchain

The meta-qt6 layer includes an example SDK recipe (meta-toolchain-qt6) which contains all the available Qt 6 modules and tools needed for building Qt applications. For easier Qt Creator integration, we have included additional CMake toolchain file (Qt6Toolchain.cmake) that can be used without sourcing the usual environment-setup script from the toolchain. Using qmake from the toolchain without sourcing the environment-setup file continues to be supported as it already is with meta-qt5.

Additionally, meta-mingw support is added to the meta-qt6 layer, which allows you to build toolchains that can be run natively on a Windows host. The Windows toolchain still has some limitations compared to native Linux development environment as not all the development tools can be currently built for MinGW.

To create your own toolchain recipe, you can use the populate_sdk_qt6_base.bbclass to include the needed configutations.

meta-qt6 vs. meta-qt5

Switching from meta-qt5 to meta-qt6 for building Qt or your own application should be quite straightforward. The recipes for Qt modules are using the same names in both layers, and starting with Qt 6.2, most of the modules from Qt5 are available in Qt6.

The two main bbclasses used in application recipes have changed:

Qt 6 is now using CMake for building itself, but qmake remains supported for application development, so you can keep your application builds using qmake.