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

Initial export of a CMake project

Construct a call to qmlprojectexporter

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.

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.

foreach(LINKER_SCRIPT IN LISTS QulExport_LINKER_SCRIPTS)
    if (IAR)
        target_link_options(mcu_minimal PRIVATE "SHELL:--config ${LINKER_SCRIPT}")
    else()
        target_link_options(mcu_minimal PRIVATE "SHELL:-T ${LINKER_SCRIPT}")
    endif()
    set_target_properties(mcu_minimal PROPERTIES LINK_DEPENDS "${LINKER_SCRIPT}")
endforeach()

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

• QulExport_APPLICATION_SOURCES
• QulExport_APPLICATION_DEFINITIONS
• QulExport_APPLICATION_INCLUDES
• QulExport_APPLICATION_LIBRARIES
• QulExport_APPLICATION_COMPILE_OPTIONS
• QulExport_APPLICATION_LINK_OPTIONS
• QulExport_APPLICATION_LINKER_SCRIPTS

Information for the exported platform port is exposed in

• QulExport_PLATFORM_SOURCES
• QulExport_PLATFORM_DEFINITIONS
• QulExport_PLATFORM_INCLUDES
• QulExport_PLATFORM_LIBRARIES
• QulExport_PLATFORM_COMPILE_OPTIONS
• QulExport_PLATFORM_LINK_OPTIONS
• QulExport_PLATFORM_LINKER_SCRIPTS

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

• QulExport_GENERIC_SOURCES
• QulExport_GENERIC_DEFINITIONS
• QulExport_GENERIC_INCLUDES
• QulExport_GENERIC_LIBRARIES
• QulExport_GENERIC_COMPILE_OPTIONS
• QulExport_GENERIC_LINK_OPTIONS
• QulExport_GENERIC_LINKER_SCRIPTS

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
cmake
    -S $QUL_ROOT
    -B <builddir>
    -DQul_ROOT=$QUL_ROOT
    -DQUL_TARGET_TOOLCHAIN_DIR=<toolchaindir>
    -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake
    -DCMAKE_TOOLCHAIN_FILE=$QUL_ROOT/lib/cmake/Qul/toolchain/armgcc.cmake
    -DQUL_PLATFORM_ARCHITECTURE=cortex-m7-hf-fpv5-d16
    -DQUL_BUILD_PLATFORM=OFF
    -DCMAKE_INSTALL_PREFIX=<installdir>
    -DQUL_PLATFORM_ARCHITECTURE_FILE=$QUL_ROOT/platform/architecture/cortex-m7-hf-fpv5-d16/armgcc/architecture.cmake
make -C <builddir> install

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

$QUL_ROOT/bin/qmlprojectexporter
    $QUL_ROOT/examples/chess/mcu_chess.qmlproject
    --boarddefaults=<path/to/>BoardDefaults_24bpp_default.qmlprojectconfig
    --toolchain GNU
    --cxx-standard=c++17
    --platform <platform_name>
    --outdir <target_dir>
    --qul-source-dir <installdir>
    --project-type cmake
    --no-export-platform
    --generate-entrypoint
    --platform-metadata <installdir>/lib/cortex-m7-hf-fpv5-d16-export.json

After this step continue with Create a CMake project file.