# New public API

A bunch of new CMake public API functions or renamed functions from `qt5_` to `qt6_`.

<br>

# qtbase

https://github.com/qt/qtbase/blob/dev/src/corelib/Qt6CoreMacros.cmake

<br>


`qt6_make_output_file` - marked deprecated in qt5, should be internal?

<br>


`qt6_get_moc_flags` - marked deprecated in qt5, should be internal?

<br>


`qt6_create_moc_command` - marked deprecated in qt5, should be internal?

<br>

^^^^^^ rename the functions above to be internal ^^^^^



`qt6_generate_moc` - renamed from qt5_, has versionless

<br>



`add_qt_gui_executable` - maybe rename to `add_qt_executable`, or `qt_add_executable`?
```cmake
function(add_qt_gui_executable target)
        add_executable("${target}" WIN32 MACOSX_BUNDLE ${ARGN})
        add_library("${target}" MODULE ${ARGN}) # android
        target_link_libraries("${target}" PRIVATE Qt::Core)
        if(TARGET Qt::Gui)
            target_link_libraries("${target}" PRIVATE Qt::Gui)
        endif()
endfunction()
```

Renamed to qt6_add_executable, and qt_add_executable

<br>


`qt6_generate_meta_types_json_file` - new, has versionless
```cmake
# Generate Qt metatypes.json for a target.
#
#  INSTALL_DIR: Location where to install the metatypes file. For public consumption defaults to a ${CMAKE_INSTALL_PREFIX}/lib/metatypes directory.
#
#  COPY_OVER_INSTALL: (Qt Internal) When present will install the file via a post build step copy rather than using install.
#
#  MANUAL_MOC_JSON_FILES: list of manually generated json files
function(qt6_generate_meta_types_json_file target)

```
It's okay to document internal options, as long as they're marked as Qt internal.
Naming is not 100% good, maybe should rename it.

<br>


`qt6_generate_win32_rc_file` - new, has versionless
```cmake
# Generate Win32 RC files for a target.
# All entries in the RC file are generated
# from target properties:
# QT_TARGET_COMPANY_NAME, QT_TARGET_DESCRIPTION, etc.
#
# The QT_TARGET_WINDOWS_RC_FILE prop can be used to specify a custom RC file instead of autogenerating one
function(qt6_generate_win32_rc_file target)

```

Make the function private, discuss upstream in CMake if this is something can be implemented in upstream CMake.


<br>

`qt6_add_plugin` - new, has versionless

```cmake
# Build a Qt plugin.
# No installation behavior.
# Might be missing some implementation details that are handled by the internal counterpart.
# Arguments:
# STATIC: Make it a static plugin
# OUTPUT_NAME: name of the plugin file
# CLASS_NAME
# TYPE: imageformats, etc
function(qt6_add_plugin target)
```

Conclusion: revisit after we have tests and after it's not TP anymore.

<br>


`qt6_disable_utf8_sources` - new, has versionless

```cmake
# By default Qt6 forces usage of utf8 sources for consumers of Qt.
# Users can opt out of utf8 sources by calling this function with the target name of their application or library.
function(qt6_disable_utf8_sources target)
```

Conclusion: Naming not perfect, consider other names.

<br>


`qt6_add_resources` - old, has versionless, new `TARGET` behavior instead of outfiles var.

```cmake
# When using this command with static libraries, one or more special targets
# will be generated. Should you wish to perform additional processing on these targets pass a value to the OUTPUT_TARGETS parameter.
function(qt6_add_resources outfiles )
    if (TARGET ${outfiles})
```

2 issues
1) old non-target based behavior doesn't handle qt quick compiler processing. this is same as qt5. might be ok to keep it like that, and just ask people to opt in to target-based behavior.
2) the new target based behavior doesn't show QML files in IDE project view, needs to be manually added via target_sources() to target to make it appear.
   Investigate if we can do that automatically.
3) Might need to discourage usage of AUTORCC because it doesn't do qt quick processing.
4) new target-based approach doesn't handle -binary option, like in `qt6_add_binary_resources`

Discussion about deprecating qrc file usage, because the CMake target-based approach is better.

<br>


https://github.com/qt/qtbase/blob/dev/src/corelib/Qt6AndroidMacros.cmake

`qt6_android_generate_deployment_settings` - new, has versionless, should be internal?

```cmake
# Generate the deployment settings json file for a cmake target.
# Uses global vars
#    ANDROID_NDK
#    ANDROID_SDK_ROOT
#    ANDROID_NDK_HOST_SYSTEM_NAME
#    CMAKE_ANDROID_ARCH_ABI
#    QT_ANDROID_APPLICATION_ARGUMENTS
#    QT_HOST_PATH
#    CMAKE_SYSROOT
# Uses target properties:
#   QT_ANDROID_DEPLOYMENT_DEPENDENCIES
#   QT_ANDROID_EXTRA_PLUGINS
#   QT_ANDROID_EXTRA_LIBS
#   QT_ANDROID_PACKAGE_SOURCE_DIR
#   QT_QML_IMPORT_PATH
#   QT_QML_ROOT_PATH
# Sets target property:
#   QT_ANDROID_DEPLOYMENT_SETTINGS_FILE
#
function(qt6_android_generate_deployment_settings target)
```

Stability of the function and variables really depends on `androiddeployqt` option compatibility, and that in turn depends on `android` itself.
So no guaranteed stability. Should be public but not internal, to allow interoperating with non-qt provided qt_add_executable wrapper.

<br>


`qt6_android_apply_arch_suffix` - new, has versionless, should be internal?

```cmake
function(qt6_android_apply_arch_suffix target)
    get_target_property(target_type ${target} TYPE)
    if (target_type STREQUAL "SHARED_LIBRARY" OR target_type STREQUAL "MODULE_LIBRARY")
        set_property(TARGET "${target}" PROPERTY SUFFIX "_${CMAKE_ANDROID_ARCH_ABI}.so")
    endif()
endfunction()
```

Keep it public. A bit more verbose compared to qt5's `CMAKE_SHARED_LIBRARY_SUFFIX_CXX`, but it's nicer.

<br>


`qt6_android_add_apk_target` - new, has versionless, should be internal?

```cmake
# Add custom target to package the APK
# Uses global vars:
#    QT_HOST_PATH
#    CMAKE_ANDROID_ARCH_ABI
#    QT_NO_GLOBAL_APK_TARGET - allow opt out of global target add_dependencies
# Uses target properties:
#   QT_ANDROID_DEPLOYMENT_SETTINGS_FILE
function(qt6_android_add_apk_target target)
```

Keep it public.

<br>


`qt6_android_get_sdk_build_tools_revision` - new, has versionless, should be internal?

```cmake
# Locate newest Android sdk build tools revision
# Uses global vars:
#   ANDROID_SDK_ROOT
function(qt6_android_get_sdk_build_tools_revision out_var)
```

Make it internal for sure.
Check if this is already provided by Android NDK, maybe we don't need to implement it.


# qtdeclarative


https://github.com/qt/qtdeclarative/blob/dev/src/qml/Qt6QmlMacros.cmake

`qt6_import_qml_plugins` - old, has versionless

```cmake
# For static builds only.
# Calls qmlimportscanner, links in used qml plugins, generates and compiles a cpp file with relevant Q_IMPORT_PLUGIN() macro calls.
#
# Arguments:
# PATH_TO_SCAN: Path to pass to qmlimportscanner to scan .qml files for the modules they use.

function(qt6_import_qml_plugins target)
```

Nothing discussed.

<br>


`qt6_add_qml_module` - new, has versionless

```cmake
# Creates a QML module.
# Arguments:
# URI: Declares the module identifier of the module (REQUIRED)

# VERSION: The module's version. (REQUIRED)

# TARGET_PATH: Overwrite the generated target path. (OPTIONAL)

# RESOURCE_PREFIX: Resource Prefix to be used when generating a static library. (OPTIONAL)

# OUTPUT_DIRECTORY: If the module is not to be built under ${CMAKE_CURRENT_BINARY_DIR}. This ensures the qmldir file is copied to the right location. (OPTIONAL)

# INSTALL_LOCATION: Intended installation directory for this module. Default installation path will be ${INSTALL_QMLDIR}. (OPTIONAL).

# DO_NOT_INSTALL_METADATA: Will not install supporting files.

# INSTALL_QML_FILES: Will install the qml files along side the plugin.

# SOURCES: List of C++ sources. (OPTIONAL)

# DEPENDENCIES: List of QML Module dependencies and their versions. The module and its version must be separated via a slash(/). E.g. QtQuick/2.0

# QML_FILES: List of Qml files.

# CLASSNAME: Provides the class name of the C++ plugin used by the module. (REQUIRED for static targets)

# DESIGNER_SUPPORTED: Specify this argument if the plugin is supported by Qt Designer (OPTIONAL)

# TYPEINFO: Path to a file which declares a type description file for the module that can be read by QML tools such as Qt Creator to access information about the types defined by the module's plugins. (OPTIONAL)

# IMPORTS: List of other Qml Modules that this module imports. (OPTIONAL)

# OPTIONAL_IMPORTS: List of other Qml Modules that this module may import at
# run-time. Those are not automatically imported by the QML engine when
# importing the current module, but rather serve as hints to tools like
# qmllint. (OPTIONAL)

# RESOURCE_EXPORT: In static builds, processed QML files are compiled into a static lib, this names the target.

# SKIP_TYPE_REGISTRATION: When present will cause the generated qmldir file
# to not list any qml types. These are expected to be registered by the
# c++ plugin code instead.

# PLUGIN_OPTIONAL: The plugin is marked as optional in the qmldir file.

function(qt6_add_qml_module target)
```

Revisit after we have tests.


`qt6_target_qml_files` - new, has versionless

```cmake
# Add Qml files (.qml,.js,.mjs) to a Qml module. This will also append the
# qml files to the qmldir file of the module. Source file properties can
# be used to control the generated qmldir entry.

# QT_QML_SOURCE_VERSION: Version(s) for this qml file.

# QT_QML_SOURCE_TYPENAME: Override the file's type name.

# QT_QML_SINGLETON_TYPE: The qml file contains a singleton type.

# QT_QML_INTERNAL_TYPE: When set to true, the type specified by

# QT_QML_SOURCE_TYPENAME will not be available to users of this module.

# QT_QML_SKIP_QMLDIR_ENTRY: No qmldir entry will be created for the source file. Useful if a file needs to be installed (like a private JS file) but does not expose a public type.

function(qt6_target_qml_files target)
```

Revisit after we have tests.

<br>


`qt6_qml_type_registration` - new, has versionless, should be internal?

```cmake
# Creates a .qmltypes file and compiles an auto-generated "${target}_qmltyperegistrations.cpp" file.

# Target properties used:
# QT_QMLTYPES_FILENAME: Used for the name of the generated file.
# QT_QML_MODULE_URI: Module URI of target
# QT_QML_MODULE_VERSION: Module version
# QT_QML_MODULE_INSTALL_DIR: Install location for .qmltypes file
# QT_QML_MODULE_INSTALL_QMLTYPES: Whether to install the .qmltypes file

# Sets properties:
# QT_QML_MODULE_PLUGIN_TYPES_FILE - path to the generated .qmltypes file

function(qt6_qml_type_registration target)
```

Revisit after we have tests.


# qtquick3d



https://github.com/qt/qtquick3d/blob/dev/src/quick3d/Qt6Quick3DMacros.cmake

`qt6_quick3d_build_shaders` - new, has versionless

```cmake
# Generates shaders from the given files and links the compiled resource files into ${target}.
#
# Arguments used:
# resource_name: creates .qrc file based on value of the argument
# FILES: list of shader file paths

function(qt6_quick3d_build_shaders target resource_name)
```

Naming not consistent, bring it up with quick3d team. we use generate usually, but generate_shared sounds a bit wrong.
Should the module name really be in the function name, is it super specific for quick3d.



# qtshadertools


https://github.com/qt/qtshadertools/blob/dev/src/shadertools/Qt6ShaderToolsMacros.cmake

`qt6_add_shaders` - new, has versionless

```cmake
# Invokes qsb on each file in FILES. Extensions must be .vert, .frag, or .comp.
# The resulting .qsb files are added as resources under PREFIX.
# target and resourcename are like for qt6_add_resources.
# Uses qt6_add_resources.
#
# Arguments used:
#
#  FILES: list of file paths, e.g.  color.vert

#  DEFINES: list of custom macros for glslang

#  PREFIX: Qt resource prefix to use, e.g  "/shaders"
#
#  BATCHABLE: enable generating batchable vertex shader variants

#  PRECOMPILE: invoke native tools where applicable

#  PERTARGETCOMPILE: compile to SPIR-V and translate separately per output language version

#  NOGLSL:  skip generating the language
#  NOHLSL:  skip generating the language
#  NOMSL: skip generating the language

#  DEBUGINFO: generate full debug
#  OPTIMIZED: optimize for performance

#  GLSL: override the version to generate
#  HLSL: override the version to generate
#  MSL: override the version to generate

function(qt6_add_shaders target resourcename)
```

Consumed by qt3d and RHI, so naming is not too generic, seems fine.


# qtremoteobjects

https://github.com/qt/qtremoteobjects/blob/dev/src/remoteobjects/Qt5RemoteObjectsMacros.cmake
https://github.com/qt/qtremoteobjects/blob/dev/src/remoteobjects/Qt6RemoteObjectsMacros.cmake

The remote objects cmake api was inspired by dbus macros.

All the functions below seem to implement what `qt5_generate_repc` does, but with completely new names and arguments. `qt5_generate_repc` is not ported to `qt6_` atm.

Conclusion: Remove qt5 style api, consistency with dbus is better, thus breaking api qt5 -> qt6 is okay.

<br>

`qt6_add_repc_files` - new, no versionless yet

```cmake
# Calls `repc` on list of FILES and adds them as `target` sources.
#
# Arguments:
# type: one of 'source', 'replica', 'merged'
# FILES: list of files to call repc on
function(qt6_add_repc_files type target)
```

Conclusion: Make the main one internal, keep only the wrapper ones public

<br>

`qt6_add_repc_source` - new, no versionless yet

Calls `qt6_add_repc_files` with `type` set to `source`.


<br>

`qt6_add_repc_replica` - new, no versionless yet

Calls `qt6_add_repc_files` with `type` set to `replica`.

<br>


`qt6_add_repc_merged` - new, no versionless yet

Calls `qt6_add_repc_files` with `type` set to `merged`.

<br>


`qt6_rep_from_header` - new, no versionless yet

```cmake
# Creates a .rep interface file from a QObject header
#
# Arguments:
# ${ARGN}: list of files to run `repc -o rep` on.
function(qt6_rep_from_header target)
```

Rename to `qt6_generate_rep`.