Introduce QTP0003 which controls the BUILD_SHARED_LIBS impact on user projects

Since 6.7 we consider the BUILD_SHARED_LIBS when creating libraries
using Qt CMake API. This change may affect the user projects that rely
on the old strategy of selecting the default library type. To preserve
the old behavior this change introduces the QTP0003 policy that allows
user to control whether the BUILD_SHARED_LIBS should or shouldn't be
considered in library creation process.

The policy doesn't affect Qt repos, we assume that we want the NEW
behavior by default.

Fixes: QTBUG-121707
Pick-to: 6.7
Change-Id: I4bcfbd8966839731624e3f7ef9e0d6bb2782ac50
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

2 files changed, 51 insertions, 4 deletions

diff --git a/src/corelib/doc/src/cmake/policy/qtp0003.qdoc b/src/corelib/doc/src/cmake/policy/qtp0003.qdoc
new file mode 100644
index 0000000000..70aef6466c
--- /dev/null
+++ b/src/corelib/doc/src/cmake/policy/qtp0003.qdoc
@@ -0,0 +1,46 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-cmake-policy-qtp0003.html
+\ingroup qt-cmake-policies
+\since 6.7
+\title QTP0003
+\keyword qt_cmake_policy_qtp0003
+
+\summary {Consider the BUILD_SHARED_LIBS value when creating Qt libraries.}
+
+This policy was introduced in Qt 6.7. The policy affects the default type of the
+libraries created using \l {Qt CMake API}{CMake Commands in Qt6 Core}, like
+\l {qt_add_library}, \l{qt_add_plugin}, \l{qt_add_qml_module}.
+
+If the policy is set to \c OLD, the default library type that is selected is
+aligned with the Qt build type, either \c shared or \c static.
+
+If the policy is set to \c NEW, the library type is selected according to the
+\l {BUILD_SHARED_LIBS}{CMake BUILD_SHARED_LIBS Documentation} value if it's set.
+If \c BUILD_SHARED_LIBS is not set, the default library type falls back to the
+Qt build type.
+
+For example, the following code will use the Qt build type as the default
+library type for the \c MyLib target, despite the fact \c BUILD_SHARED_LIBS is
+set to \c ON:
+\badcode
+set(BUILD_SHARED_LIBS ON)
+...
+qt6_add_library(MyLib sourcefile.h sourcefile.cpp)
+\endcode
+
+If you set the QTP0003 to \c NEW before the \l {qt6_add_library}{qt_add_library}
+call, \c BUILD_SHARED_LIBS will affect the library default type and \c MyLib
+will be the shared library.
+\badcode
+set(BUILD_SHARED_LIBS ON)
+...
+qt_policy(SET QTP0003 NEW)
+qt6_add_library(MyLib sourcefile.h sourcefile.cpp)
+\endcode
+
+\sa qt_policy, {Qt CMake policies}, qt_add_library
+
+*/
diff --git a/src/corelib/doc/src/cmake/qt_add_library.qdoc b/src/corelib/doc/src/cmake/qt_add_library.qdoc
index ed6e770516..851a2d6210 100644
--- a/src/corelib/doc/src/cmake/qt_add_library.qdoc
+++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc
@@ -45,9 +45,10 @@ library type created depends on how Qt was built. If Qt was built statically,
 a static library will be created. Otherwise, a shared library will
 be created. Note that this is different to how CMake's \c{add_library()}
 command works, where the \c BUILD_SHARED_LIBS variable controls the type of
-library created. The \c{qt_add_library()} command considers
-\c BUILD_SHARED_LIBS when deciding the library type only if the variable is set
-explicitly.
+library created.
+Since 6.7, the \c{qt_add_library()} command considers \c BUILD_SHARED_LIBS
+when deciding the library type only if the variable is set explicitly and
+\l {QTP0003} is set to \c NEW.
 
 Any \c{sources} provided will be passed through to the internal call to
 \c{add_library()}.
@@ -74,6 +75,6 @@ time. In general, \c MANUAL_FINALIZATION should not be needed unless the
 project has to support CMake 3.18 or earlier.
 
 \sa {qt6_finalize_target}{qt_finalize_target()},
-    {qt6_add_executable}{qt_add_executable()}
+    {qt6_add_executable}{qt_add_executable()}, QTP0003
 
 */