qt_extract_metatypes

Extracts metatypes from a Qt target and generates an associated metatypes.json file.

This command was introduced in Qt 6.0.

Synopsis

 qt_extract_metatypes(target
     [MANUAL_MOC_JSON_FILES json_files...]
     [OUTPUT_FILES variable_name]
 )

If versionless commands are disabled, use qt6_extract_metatypes() instead. It supports the same set of arguments as this command.

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, qt_extract_metatypes() can be called to force the collection of this information for a specific target.

Metatype information is generated for a target's source files in one of the following ways:

• Automatically by AUTOMOC. The qt_extract_metatypes() command detects when AUTOMOC is enabled on the target and will automatically extract the information it needs.
• Manually by invoking moc with the --output-json option. The project is responsible for keeping track of all the JSON files generated using this method and passing them to qt_extract_metatypes() with the MANUAL_MOC_JSON_FILES option.

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 moc with the --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 OUTPUT_FILES option to provide the name of a variable in which to store its absolute path.

Automatic metatype extraction

Since Qt 6.8, if you have not disabled AUTOMOC and either are using CMake 3.19 or later or are calling qt_finalize_target() manually, then qt_extract_metatypes() is automatically called as part of the finalization step for qt_add_library. This has no effect if you have manually called 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, qt_add_qml_module automatically invokes qt_extract_metatypes() for its target.