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

Warning
It is now recommended to actively drop Qt5 support wherever possible. Plasma 6 is stable for proper Qt6 integration, and Qt5 will need removal sooner than later due to the limited support for the non-commercial version.

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 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 (-r500, -r600)

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 )"

For a more troublesome example, a library that can only support either Qt 5 or Qt 6. First, consider one of the following options (especially for a non-niche library that many users will be installing):

• Still try to support both at once, e.g. with multibuild.eclass if libraries can coexist
• Drop support for the old Qt version entirely (including in reverse dependencies)
• Use revision "fake" slotting (-r500, -r600) for a smoother transition but only if reverse dependencies can align (all qt5 or all qt6 to avoid conflicts, safe if only one package)

If deemed too troublesome, a last option that is acceptable for niche libraries but still discouraged (similar end result as revision slotting that is easier to maintain but requires more work from users), is:

• Implement both qt5 and qt6 USE flags
• Set REQUIRED_USE="^^ ( qt5 qt6 )"
• Default to qt5 but remember that this will be extra troublesome when qt6 becomes a default on a profile and other options should be reconsidered
• Do not try to avoid the above REQUIRED_USE by implementing "default to qt5 if both are set" then have reverse dependencies depend on [qt6,-qt5] as this affects users all the same and is misleading