1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qt-extract-metatypes.html
6\ingroup cmake-commands-qtcore
8\title qt_extract_metatypes
9\keyword qt6_extract_metatypes
11\summary {Extracts metatypes from a Qt target and generates an associated metatypes.json file.}
14\preliminarycmakecommand
19qt_extract_metatypes(target
20 [MANUAL_MOC_JSON_FILES json_files...]
21 [OUTPUT_FILES variable_name]
25\versionlessCMakeCommandsNote qt6_extract_metatypes()
29Certain operations rely on metatype information being generated and collected
30on targets. This is typically handled internally by Qt commands, but for
31scenarios where this is not the case, \c{qt_extract_metatypes()} can be called
32to force the collection of this information for a specific \c target.
34Metatype information is generated for a target's source files in one of the
38\li Automatically by AUTOMOC. The \c{qt_extract_metatypes()} command detects
39 when AUTOMOC is enabled on the \c target and will automatically extract the
41\li Manually by invoking \c moc with the \c{--output-json} option. The project
42 is responsible for keeping track of all the JSON files generated using this
43 method and passing them to \c{qt_extract_metatypes()} with the
44 \c MANUAL_MOC_JSON_FILES option.
47\c{qt_extract_metatypes()} produces a target-specific metatypes JSON file which
48collects all the metatype details from the AUTOMOC and manual moc inputs.
49It does this by calling \c moc with the \c{--collect-json} option.
50If you need to know where to find the resultant metatypes JSON file (for
51example, to pass it to another command or to install it), use the
52\c OUTPUT_FILES option to provide the name of a variable in which to store its
55\section1 Automatic metatype extraction
57Since Qt 6.8, if you have not disabled \c{AUTOMOC} and either are using CMake
583.19 or later or are calling \l{qt6_finalize_target}{qt_finalize_target()}
59manually, then \c{qt_extract_metatypes()} is automatically called as part of the
60finalization step for \l{qt_add_library}. This has no effect if you have
61manually called \c{qt_extract_metatypes()} before the finalization, possibly
62with custom arguments. However, it does make sure that the metatypes are also
63produced if you haven't. This is important if any of the types in the library
64are used as part of any QML types any time in the future and has no downsides.
66Furthermore, \l{qt_add_qml_module} automatically invokes
67\c{qt_extract_metatypes()} for its target.