From cc60cf83db6bbf9775b1f7747a48d6b7eb24e585 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Thu, 23 Sep 2021 17:42:06 +1000 Subject: Add docs for qt_extract_metatypes() Also tidy up the inline TODO comments to reduce duplication and address some minor inconsistencies. Task-number: QTBUG-95712 Change-Id: Ic0d27f3c0a356fd311bba95de967faaea05e0f0a Reviewed-by: Fabian Kosmale Reviewed-by: Alexandru Croitor (cherry picked from commit 03104825d2187eca12fbfd142001618c8535eb76) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/Qt6CoreMacros.cmake | 27 ++------ .../doc/src/cmake/qt_extract_metatypes.qdoc | 78 ++++++++++++++++++++++ 2 files changed, 85 insertions(+), 20 deletions(-) create mode 100644 src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc diff --git a/src/corelib/Qt6CoreMacros.cmake b/src/corelib/Qt6CoreMacros.cmake index a927d4b91e..51fa960c5b 100644 --- a/src/corelib/Qt6CoreMacros.cmake +++ b/src/corelib/Qt6CoreMacros.cmake @@ -955,26 +955,6 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS) endfunction() endif() -# Extracts metatypes from a Qt target and generates a metatypes.json for it. -# -# By default we check whether AUTOMOC has been enabled and we extract the information from the -# target's AUTOMOC supporting files. -# -# Should you not wish to use AUTOMOC you need to pass in all the generated json files via the -# MANUAL_MOC_JSON_FILES parameter. The latter can be obtained by running moc with -# the --output-json parameter. -# Params: -# OUTPUT_FILES: a variable name in which to store the list of the extracted metatype json files. -# A typical use case would to install them. -# -# TODO: Move these internal options out into an internal function to be used by Qt only. -# __QT_INTERNAL_INSTALL_DIR: Location where to install the metatypes file. For public consumption, -# defaults to a ${CMAKE_INSTALL_PREFIX}/${INSTALL_LIBDIR}/metatypes -# directory. -# Executable metatypes files are never installed. -# __QT_INTERNAL_NO_INSTALL: When passed, will skip installation of the metatype file. -# __QT_INTERNAL_INSTALL: Installs the metatypes files into the default Qt metatypes folder. -# Only to be used by the Qt build. function(qt6_extract_metatypes target) get_target_property(existing_meta_types_file ${target} INTERFACE_QT_META_TYPES_BUILD_FILE) @@ -984,13 +964,20 @@ function(qt6_extract_metatypes target) set(args_option # TODO: Remove this once all leaf module usages of it are removed. It's now a no-op. + # It's original purpose was to skip installation of the metatypes file. __QT_INTERNAL_NO_INSTALL # TODO: Move this into a separate internal function, so it doesn't pollute the public one. + # When given, metatypes files will be installed into the default Qt + # metatypes folder. Only to be used by the Qt build. __QT_INTERNAL_INSTALL ) set(args_single # TODO: Move this into a separate internal function, so it doesn't pollute the public one. + # Location where to install the metatypes file. Only used if + # __QT_INTERNAL_INSTALL is given. It defaults to the + # ${CMAKE_INSTALL_PREFIX}/${INSTALL_LIBDIR}/metatypes directory. + # Executable metatypes files are never installed. __QT_INTERNAL_INSTALL_DIR OUTPUT_FILES diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc new file mode 100644 index 0000000000..4a1b0c551c --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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_extract_metatypes.html +\ingroup cmake-macros-qtcore + +\title qt_extract_metatypes +\target qt6_extract_metatypes + +\brief Extracts metatypes from a Qt target and generates an associated metatypes.json file. + +\preliminarycmakecommand + +\section1 Synopsis + +\badcode +qt_extract_metatypes(target + [MANUAL_MOC_JSON_FILES json_files...] + [OUTPUT_FILES variable_name] +) +\endcode + +\versionlessCMakeCommandsNote qt6_extract_metatypes() + +\section1 Description + +Certain operations rely on metatype information being generated and collected +on targets. This is typically handled internally by Qt commands, but for +scenarios where this is not the case, \c{qt_extract_metatypes()} can be called +to force the collection of this information for a specific \c target. + +Metatype information is generated for a target's source files in one of the +following ways: + +\list +\li Automatically by AUTOMOC. The \c{qt_extract_metatypes()} command detects + when AUTOMOC is enabled on the \c target and will automatically extract the + information it needs. +\li Manually by invoking \c moc with the \c{--output-json} option. The project + is responsible for keeping track of all the JSON files generated using this + method and passing them to \c{qt_extract_metatypes()} with the + \c MANUAL_MOC_JSON_FILES option. +\endlist + +\c{qt_extract_metatypes()} produces a target-specific metatypes JSON file which +collects all the metatype details from the AUTOMOC and manual moc inputs. +It does this by calling \c moc with the \c{--collect-json} option. +If you need to know where to find the resultant metatypes JSON file (for +example, to pass it to another command or to install it), use the +\c OUTPUT_FILES option to provide the name of a variable in which to store its +absolute path. + +*/ -- cgit v1.2.3