From f82653c9735909f60efc6379abdb24803926ffa3 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 17 Sep 2021 18:43:56 +1000 Subject: Document qt_add_library() and update related docs Task-number: QTBUG-95712 Pick-to: 6.2 6.2.0 Change-Id: Ib107110457380a2bb30876cf2c565f0c8e8c5e9c Reviewed-by: Alexandru Croitor Reviewed-by: Venugopal Shivashankar Reviewed-by: Joerg Bornemann --- src/corelib/doc/src/cmake/cmake-variables.qdoc | 33 ++++++++ src/corelib/doc/src/cmake/qt_add_executable.qdoc | 3 +- src/corelib/doc/src/cmake/qt_add_library.qdoc | 97 +++++++++++++++++++++++ src/corelib/doc/src/cmake/qt_finalize_target.qdoc | 66 ++++++++++++--- 4 files changed, 186 insertions(+), 13 deletions(-) create mode 100644 src/corelib/doc/src/cmake/qt_add_library.qdoc (limited to 'src/corelib/doc') 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. + */ -- cgit v1.2.3