Document qt_add_library() and update related docs

Task-number: QTBUG-95712
Change-Id: Ib107110457380a2bb30876cf2c565f0c8e8c5e9c
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
(cherry picked from commit f82653c9735909f60efc6379abdb24803926ffa3)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 186 insertions, 13 deletions

diff --git a/src/corelib/doc/src/cmake/cmake-variables.qdoc b/src/corelib/doc/src/cmake/cmake-variables.qdoc
index d3f73ab918..bae057c23e 100644
--- a/src/corelib/doc/src/cmake/cmake-variables.qdoc
+++ b/src/corelib/doc/src/cmake/cmake-variables.qdoc
@@ -98,3 +98,36 @@ When cross-compiling, this must be set to the install location of Qt for the hos
 platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc},
 \l{androiddeployqt}, and so on).
 */
+
+/*!
+\page cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID.html
+\ingroup cmake-variables
+\ingroup cmake-variables-qtcore
+
+\title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID
+\target cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID
+
+\brief Disables providing a fallback team ID during target finalization on iOS.
+
+When finalizing an executable target on iOS,
+\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's
+\c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM property if it hasn't been set.
+Set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to true if you want to prevent this.
+*/
+
+/*!
+\page cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER.html
+\ingroup cmake-variables
+\ingroup cmake-variables-qtcore
+
+\title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER
+\target cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER
+
+\brief Disables providing a fallback app bundle ID during target finalization on iOS.
+
+When finalizing an executable target on iOS,
+\l{qt6_finalize_target}{qt_finalize_target()} will populate the target's
+\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and
+\c MACOSX_BUNDLE_GUI_IDENTIFIER properties if they haven't been set.
+Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this.
+*/
diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc
index a817aa71f5..e240086059 100644
--- a/src/corelib/doc/src/cmake/qt_add_executable.qdoc
+++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc
@@ -96,7 +96,8 @@ indicate that you will explicitly call \l{qt6_finalize_target}{qt_finalize_targe
 yourself instead at some later 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()}
+\sa {qt6_finalize_target}{qt_finalize_target()},
+    {qt6_add_library}{qt_add_library()}
 
 \section1 Examples
 
diff --git a/src/corelib/doc/src/cmake/qt_add_library.qdoc b/src/corelib/doc/src/cmake/qt_add_library.qdoc
new file mode 100644
index 0000000000..f2b9042b72
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc
@@ -0,0 +1,97 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qt_add_library.html
+\ingroup cmake-macros-qtcore
+
+\title qt_add_library
+\target qt6_add_library
+
+\brief Creates and finalizes a library.
+
+\section1 Synopsis
+
+\badcode
+qt_add_library(target
+    [STATIC | SHARED | MODULE | INTERFACE | OBJECT]
+    [MANUAL_FINALIZATION]
+    sources...
+)
+\endcode
+
+\versionlessCMakeCommandsNote qt6_add_library()
+
+\section1 Description
+
+\c{qt_add_library()} is a wrapper around CMake's built-in
+\c{add_library()} command. It performs the following tasks:
+
+\list
+\li Create a CMake target of an appropriate library type.
+\li Handle finalization of the CMake target.
+\endlist
+
+\section2 Target Creation
+
+The type of library created can be specified explicitly with one of the
+\c STATIC, \c SHARED, \c MODULE, \c INTERFACE or \c OBJECT keywords, just as
+one might for \c{add_library()}. If none of these keywords are given, the
+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 does not consider
+\c BUILD_SHARED_LIBS when deciding the library type.
+
+Any \c{sources} provided will be passed through to the internal call to
+\c{add_library()}.
+
+\section2 Finalization
+
+After a target is created, further processing or \e{finalization} steps may be
+needed. The finalization processing is implemented by the
+\l{qt6_finalize_target}{qt_finalize_target()} command.
+
+Finalization can occur either as part of this call or be deferred to sometime
+after this command returns (but it should still be in the same directory scope).
+When using CMake 3.19 or later, finalization is automatically deferred to the
+end of the current directory scope. This gives the caller an opportunity to
+modify properties of the created target before it is finalized. When using
+CMake versions earlier than 3.19, automatic deferral isn't supported. In that
+case, finalization is performed immediately before this command returns.
+
+Regardless of the CMake version, the \c{MANUAL_FINALIZATION} keyword can be
+given to indicate that you will explicitly call
+\l{qt6_finalize_target}{qt_finalize_target()} yourself instead at some later
+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()}
+
+*/
diff --git a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc
index da4a8eeaae..0d01e52227 100644
--- a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc
+++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc
@@ -45,21 +45,63 @@ qt_finalize_target(target)
 \section1 Description
 
 After a target is created, further processing or \e{finalization} steps are
-commonly needed. The steps to perform depend on the platform and on various
-properties of the target. These steps are expected to be performed within the
-same directory scope as the one in which the \c{target} was created, so this
-command should also be called from that same directory scope.
+sometimes needed. The steps to perform depend on the platform, the type of
+target, and on various properties of the target. These steps are expected to be
+performed within the same directory scope as the one in which the \c{target}
+was created, so this command should also be called from that same directory
+scope.
 
-This command implements the following, as appropriate for the platform and
-target provided:
+This command is ordinarily invoked as part of a call to
+\l{qt6_add_executable}{qt_add_executable()} or
+\l{qt6_add_library}{qt_add_library()}. The timing of when that call takes
+place and when it might need to be called explicitly by a project is discussed
+in the documentation of those commands.
+
+\section1 Executable Targets
+
+For executable targets, \c{qt_finalize_target()} implements the logic described
+in the subsections below, as appropriate for the platform and target provided.
+Later Qt releases may expand finalization processing further.
+
+\section2 All Platforms
+
+Some internal processing is performed to facilitate automatic linking of Qt
+plugins. This is especially important if using a statically built Qt or a
+CMake version earlier than 3.21.
+
+\section2 Android
 
 \list
-\li When targeting Android, generate a deployment settings file for the target.
-\li Create a build target for generating an APK if building for Android.
+\li Generate a deployment settings file for the \c target.
+\li Create a build target for generating an APK.
 \endlist
 
-This command is ordinarily invoked as part of a call to
-\l{qt6_add_executable}{qt_add_executable()}. The timing of when that call takes
-place and when it might need to be called explicitly by a project is discussed
-in the documentation of that command.
+\section2 WASM
+
+Create \c{${target}.html} (a target-specific \c{wasm_shell.html} file),
+\c{qtloader.js} and \c{qtlogo.svg} files in the \c{CMAKE_CURRENT_BINARY_DIR}.
+
+\section2 iOS
+
+Finalization attempts to provide sensible values for the following target
+properties if they are not already set, and their corresponding \c{CMAKE_...}
+variable is also not set:
+
+\list
+\li \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM
+\li \c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER
+\li \c MACOSX_BUNDLE_GUI_IDENTIFIER
+\endlist
+
+If required, the \l QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID variable can be used to
+disable setting \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM, and the
+\l QT_NO_SET_XCODE_BUNDLE_IDENTIFIER variable can be used to disable setting
+\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and \c MACOSX_BUNDLE_GUI_IDENTIFIER.
+
+\section1 Library Targets
+
+As of this Qt version, finalization for library targets does not perform any
+processing. Future Qt versions may add finalization processing for libraries,
+so you should ensure finalization is still invoked in the expected way.
+
 */