Project:Qt/Policies

General policies

• Do not add random new packages to the dev-qt category, it is reserved for the Qt framework modules and directly related libraries and development applications from the upstream Qt Project.

• Changes to Qt packages should be reviewed by a project member prior to being committed.

• In the case of minor changes (e.g. typos, pkgmoved dependencies, etc.), please notify the team. Most of our packages are bumped out of the overlay and tree changes will be lost if not also made there.

• QA policy on USE=gui should be followed

Dependencies

• Explicitly depend on all Qt modules that are used - do not rely on transitive dependencies (including dev-qt/qtcore).
• Specify the correct slot - most Qt modules have two major versions.
• The := subslot dependency operator must only be used for packages that are known to use a private part of the Qt API.

Handling different versions of Qt

We recommend all packages with a Qt dependency follow these recommendations to ensure a consistent user experience.

Avoiding unnecessary REQUIRED_USE is important to minimise user interaction, especially as USE="qt5 qt6" becomes a common configuration.

Optional support for a single Qt version

For example, a CLI application with an optional Qt GUI.

• If the package has no other GUI toolkit support, implement USE=gui.
• If the package supports two Qt versions (Qt 5 and Qt 6) but upstream prefer Qt 5, implement USE=gui and USE=qt6. USE=gui would use qt5.
• Depending on the Qt version required, implement the appropriate USE flag: qt5 or qt6.

Optional support for one of two Qt versions

For example, a CLI application with an optional GUI that can be built with Qt 5 or Qt 6.

• Implement both qt5 and qt6 USE flags
• When both qt5 and qt6 USE flags are enabled, prefer qt5
• Do not use REQUIRED_USE="?? ( qt5 qt6 )"

Optional support for two Qt versions

For example, a library with both Qt 5 and Qt 6 bindings (example: app-text/poppler).

• Implement both qt5 and qt6 USE flags

Requires one of two Qt versions

For example, a Qt-based media player that can be built with either Qt 5 or Qt 6 (example: net-irc/quassel).

• Implement a qt6 USE flag to choose Qt 6
• Do not implement a qt5 USE flag and do not use REQUIRED_USE="^^ ( qt5 qt6 )"

Requires at least one Qt version

For example, a library with a SONAME that changes based on which Qt version it was built against (example: media-libs/phonon).

• Implement both qt5 and qt6 USE flags
• Enable the qt5 USE flag by default: USE="+qt5"
• Add REQUIRED_USE="|| ( qt5 qt6 )"
• Use multibuild eclass instead of revision slotting (-r400, -r500)