Backstory.
The main reason why we keep getting "unable to promote 3rd party 'X'
target to global scope" errors when building Qt repositories, is
because we try to promote 3rd party imported targets in a different
scope than where the imported targets were created.
What were the main motivations for promoting 3rd party targets to
global?
1) imported targets are by default local to the directory scope they
were created in
2) we want 3rd party targets to be accessible across subdirectory
scopes, but looked up once, e.g. qt_find_package(JPEG) looked up in
src/gui/CMakeLists.txt, but the target should also be usable in the
sibling scope
src/plugins/imageformats/CMakeLists.txt
Having the package lookup close to the consuming qt module is easier
to maintain, because all the other 3rd party dependency lookups are
in the same file. This goes against the conventional CMake advice
where each subdirectory should look for its own dependencies, or the
dependency should be available directly in the root project scope.
3) to make the 3rd party targets available in the root project scope
as part of the following flow:
QtPostProcess.cmake ->
qt_internal_create_module_depends_file() ->
qt_collect_third_party_deps() ->
get_property(INTERFACE_QT_PACKAGE_NAME) ->
write 3rd party Dependencies.cmake file for each qt module.
Properties can only be queried from an imported target if it's in
the same scope or was promoted to global, otherwise you get
'non-existent target' errors.
4) for prl and pri file generation, where we need the targets to be
available during generator expression evaluation within the
relevant qt module directory scope
Here is a list of approaches I came up with on how to improve the
situation.
1) Make all imported targets global during the Qt build, by iterating
over the directory property IMPORTED_TARGETS and making each one
global.
Requires CMake 3.21.
Status: Already implemented for a long time, but is opt-in.
Pros: Relatively robust
Cons: Minimum CMake version for building Qt is 3.16.
2) Make all imported targets global during the Qt build using the
CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable.
Requires CMake 3.24.
Status: Not implemented, but can be set by Qt builders directly on
the command line.
Pros: Should be robust
Cons: Minimum CMake version for building Qt is 3.16.
3) Abandon the desire to have a single qt_find_package in a single
directory scope, and embrace the CMake-way of repeating the
dependency in each subdirectory that requires it.
Status: Not implemented.
Pros: Should be robust
Cons: A lot of qt_find_package duplication, will require rewriting
various code paths, QtPostProcess would have to be done at
directory scope, unclear if dependency tracking will still work
work reliably when there might be multiple same-named
directory-scoped targets, other unknown unknowns
4) Move all qt_find_package calls into a $repo_name/dependencies.cmake
file which would be read at project root scope. This would
potentially avoid all scoping issues, because all dependencies will
have to be specified at root scope.
Status: Not implemented.
Pros: No duplication
Cons: Dependencies are not scoped anymore to module directories,
won't be able to conditionally look for dependencies based on
module feature evaluation, not clear yet how this will tie into
standalone tests which are in tests/ subdir, other unknown unknowns
5) Try to promote as many 3rd party libraries at project root scope
as possible.
Currently we have 2 general locations where we look up
dependencies.
One is each qt_find_package call. The other is
Qt6FooDependencies.cmake ->
_qt_internal_find_third_party_dependencies().
Many 3rd party targets are created by
_qt_internal_find_third_party_dependencies() in the root scope, but
not promoted, and then we try to promote them in child scopes using
qt_find_package, which causes the promotion errors.
Starting with 58eefbd0b6 and
37a5e001277db9e1392a242171ab2b88cb6c3049 we now record the provided
targets of previous qt_find_package calls.
So instead of waiting to try and promote targets later during the
configuration process, we can make sure we promote the targets at
_qt_internal_find_third_party_dependencies() call time, right
when we lookup the Qt dependencies of the qt repo, in the root
scope.
Status: Implemented in this change
Notably, we only promote 3rd party targets to global for qt builds,
and not user projects, to not accidentally break user project
behaviors.
Also, we only promote 3rd party targets, and not Qt internal
targets like Qt6::Core, Qt6::Platform, Qt6::PlatformCommonInternal,
Qt6::GlobalConfig, etc, for a few reasons:
- the code that requires targets to be global only cares about
3rd party targets
- promoting the internal targets is more prone to breaking, because
there is more than one place where find_package(Qt6Foo) might be
called, and if that ends up being in a different directory scope,
we encounter the same global promotion errors.
Some notable cases where this happens:
- tests/CMakeLists.txt brings in extra Qt packages via
StandaloneTestsConfig.cmake files
- qtbase standalone tests qt_internal_qtbase_pre_project_setup()
calls find_package(Qt6 COMPONENTS BuildInternals) which ends
up creating the Platform target in the root scope instead of
the tests/ scope
- Qt6::BundledLibpng links against Core, which ends up trying to
promote Core's internal dependencies Platform and GlobalConfig
To only promote 3rd party targets, we walk the dependencies of
an initial target recursively, and skip promoting targets that have
the _qt_is_internal_target or
_qt_should_skip_global_promotion_always properties set.
Pros: Improves the situation compared to the status quo
Cons: Still not ideal due to the various filtering of internal
targets and having to mark them as such.
6) Avoid promoting targets to global if we can detect that the target
was created in a different scope than where we are trying to
promote it.
We can do that by comparing the target's BINARY_DIR to the
CMAKE_CURRENT_BINARY_DIR and skip promotion if they are not equal.
Status: Not implemented, but we can consider it because it's
quick to do.
Pros: More robust than newly implemented approach (5)
Cons: Requires CMake 3.18, because trying to read the BINARY_DIR
property on an INTERFACE_LIBRARY would error out.
Also, if we implement it and make it the default when using 3.18+,
we might 'collect' a lot more hidden promotion errors that will
only be revealed later once someone uses CMake 3.16 or 3.17,
because most will probably use newer CMake versions.
Perhaps the trade-off is worth it?
Fixes: QTBUG-89204
Fixes: QTBUG-94356
Fixes: QTBUG-95052
Fixes: QTBUG-98807
Fixes: QTBUG-125371
Change-Id: I088a17a98ef35aa69537a3ad208c61de40def581
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
(cherry picked from commit d2e85cede01c0898ca73cbc3fb9f53aa9612cab5)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
5da0b7624f