Generating CMake projects

This page covers extra information regarding the generation of CMake projects.

Initial export of a CMake project

Construct a call to qmlprojectexporter

${QUL_DIR}/bin/qmlprojectexporterTool to be called.
path/to/some.qmlprojectQML project file to be exported
--platform <platform_name>Platform name that is to be exported
--project-type cmakeUse CMake output project format
--toolchain <compiler_id>This provides information about which compiler type the generated options should be compatible with. Possible optionsare gnu, ghs, iar, or msvc.

Note: For all GCC-compatible compilers, use "gnu".

--cxx-standard <C++ standard>Optionally specify the C++ standard to use when processing the interface files listed in the InterfaceFiles block of the QML project file.
--outdir <path>Path the project will be exported to.
--ide-sources-outdir <outdir>
To include the 3rd party platform code in the export use these two options. The output directory can be inside the platform output directory. For example <platform_outdir>/QtMCUs/platform, but any other location is fine as well. You likely want to skip these when exporting to a 3rd-party IDEs like STM32CubeIDE or MCUXpresso IDE.
--generate-entrypointProviding this optional option will generate a main function with a default code to run your QML application.
--boarddefaults=<qul_dir>/platform/boards/<platform>/cmake/BoardDefaults_32bpp_default.qmlprojectconfigThe board defaults need to be provided per board to provide information about color depth and asset formats.
--selector a[,b...]In case your QML project uses selectors to find QML files and resources, provide these as a comma separated list.

Options for custom built Qt Quick Ultralite library

To create the metadata for a platform export, you must enable metadata creation. In your Qt Quick Ultralite build directory, create an empty file and the folders if necessary under .cmake/api/v1/query/codemodel-v2. Run CMake to reconfigure and build again.

--qul-source-dir ${QUL_DIR}The source tree of Qt Quick Ultralite. This has only to be provided if your Qt Quick Ultralite tools are located in a custom location.
--qul-build-dir <dir>The build directory of the Qt Quick Ultralite core library. This has to be provided if you are (re-)building the Qt Quick Ultralite core library.
--verboseOptionally show detailed commands when running qmlprojectexporter
--platform-boards-sources-dir=<dir>In case the boards sources are not located in ${QUL_DIR}/platform/boards use this option to specify the path.

Create a CMake project file

After exporting a project with the command described above, a CMake package is created in the output folder.

To use this package some lines need to be added to your CMake project.

project(<name> LANGUAGES C CXX ASM)

The ASM is important because depending on your platform/compiler the export will generate assembly files. When this option is missing, CMake will silently drop all assembly files without any notification.

find_package(QulExport REQUIRED PATHS "<exported_path>" NO_DEFAULT_PATH)

This will Load the exported information into your current project. The PATHS variable given to find_package() has to point to the path where you exported the project to.

The exported information is provided in CMake variable lists and have to be added to your CMake target. For details on these variables, see the next chapters.

target_sources(<my_target> PRIVATE ${QulExport_SOURCES})
target_compile_definitions(<my_target> PRIVATE ${QulExport_DEFINITIONS})
target_include_directories(<my_target> PRIVATE ${QulExport_INCLUDES})
target_compile_options(<my_target> PRIVATE ${QulExport_COMPILE_OPTIONS})
target_link_options(<my_target> PRIVATE ${QulExport_LINK_OPTIONS})
target_link_libraries(<my_target> PRIVATE ${QulExport_LIBRARIES})

If your build system does not handle the linker sections, you have to add the provided linker script to the options.

    if (IAR)
        target_link_options(mcu_minimal PRIVATE "SHELL:--config ${LINKER_SCRIPT}")
        target_link_options(mcu_minimal PRIVATE "SHELL:-T ${LINKER_SCRIPT}")
    set_target_properties(mcu_minimal PROPERTIES LINK_DEPENDS "${LINKER_SCRIPT}")

Details about the exposed CMake variables

All sources and flags are exposed through variables after find_package().

find_package(QulExport REQUIRED PATHS "<exported_path>" NO_DEFAULT_PATH)
  • QulExport_SOURCES contains a list of C/C++/ASM source files to be compiled.
  • QulExport_DEFINITIIONS contains a list of required compiler defines to be set.
  • QulExport_INCLUDES contains a list of include paths.
  • QulExport_COMPILE_OPTIONS consains a list of required compiler options.
  • QulExport_LINK_OPTIONS contains a list of required linker options.
  • QulExport_LIBRARIES contains a list of libraries to be linked with.
  • QulExport_LINKER_SCRIPTS contains a list of linker scripts to be used during the linking.

Power users

There are further variables that break down the exposed information per Qt Quick Ultralite component for when a combined variables, like the ones in the previous chapter, are not sufficient. The variables follow the same naming scheme, but with the component added.

Information for the exported application is exposed in


Information for the exported platform port is exposed in


Generic information that is not assigned to the application nor the platform is exposed in


When the QML project export command includes the --generate-entrypoint option, the generated main function information is also exposed.

  • QulExport_ENTRYPOINT_ITEM contains the name of the main QML item.
  • QulExport_ENTRYPOINT_NAME contains the name of the main function.
  • QulExport_ENTRYPOINT_FUNCTION contains the function name with its signature.
  • QulExport_ENTRYPOINT_PROTOTYPE contains the prototype of the main function.
  • QulExport_ENTRYPOINT_FILEPATH contains the path to the source file including the main function.

Autogenerated CMake project

When exporting a QML application, qmlprojectexporter will generate a CMakeLists.txt that can be used directly. The CMake target name is specified with --project-target-name or will default to the QML project name when omitted. This file might be used with add_subdirectory(), but is mostly for demonstration purposes. The main way to integrate the export into CMake is the find_package() method described above.

Integrate exported projects without a platform

On build systems like Zephyr and ESP-IDF, the platform code is coming from the build system. In these cases only the QML application and custom built Qt Quick Ultralite core library is to be exported.

Build and install your custom architecture build as described in Building Qt Quick Ultralite from sources.

mkdir -p <builddir>/.cmake/api/v1/query && touch <builddir>/.cmake/api/v1/query/codemodel-v2
    -S $QUL_ROOT
    -B <builddir>
make -C <builddir> install

From this build your project can be exported into the target build system

    --toolchain GNU
    --platform <platform_name>
    --outdir <target_dir>
    --qul-source-dir <installdir>
    --project-type cmake
    --platform-metadata <installdir>/lib/cortex-m7-hf-fpv5-d16-export.json

After this step continue with Create a CMake project file.

Available under certain Qt licenses.
Find out more.