// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qt-extract-metatypes.html
\ingroup cmake-commands-qtcore

\title qt_extract_metatypes
\keyword qt6_extract_metatypes

\summary {Extracts metatypes from a Qt target and generates an associated metatypes.json file.}

\cmakecommandsince 6.0
\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.

\section1 Automatic metatype extraction

Since Qt 6.8, if you have not disabled \c{AUTOMOC} and either are using CMake
3.19 or later or are calling \l{qt6_finalize_target}{qt_finalize_target()}
manually, then \c{qt_extract_metatypes()} is automatically called as part of the
finalization step for \l{qt_add_library}. This has no effect if you have
manually called \c{qt_extract_metatypes()} before the finalization, possibly
with custom arguments. However, it does make sure that the metatypes are also
produced if you haven't. This is important if any of the types in the library
are used as part of any QML types any time in the future and has no downsides.

Furthermore, \l{qt_add_qml_module} automatically invokes
\c{qt_extract_metatypes()} for its target.

*/