C

Getting started

Before you start porting, ensure that all the prerequisites for Qt Quick Ultralite are met. This guide uses CMake in all the examples as Qt Quick Ultralite depends on the CMake build system.

This guide uses a dummy platform, example-baremetal, as an example for the porting steps. You can create your platform port based on this dummy platform or create one from scratch.

Setting up a Qt Quick Ultralite platform port project

Qt Quick Ultralite has all its supported platforms under platform directory. All platforms are under the boards subdirectory, where they are categorized based on the platform manufacturer's name. For example, the example-baremetal platform port's manufacturer is qt and the port can be found from platform\boards\qt\example-baremetal.

BOARD_MANUFACTURER_NAME is a variable that is set by qul_private_find_and_get_board_manufacturer_name macro. It is used to search for the given platform from the boards directory and return the directory where the specified port for the board resides.

To make your platform visible to Qt Quick Ultralite's CMake scripts, create a new directory for the platform:

mkdir platform/boards/<MANUFACTURER_NAME>/<YOUR_PLATFORM>
md platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>

Where <MANUFACTURER_NAME> and <YOUR_PLATFORM> can be named however you want.

You must add a CMakeLists.txt file for both the <MANUFACTURER_NAME> and the <YOUR_PLATFORM> directories. The CMakeLists.txt under <YOUR_PLATFORM> is configured in Creating the configuration file for you platform. The one under <MANUFACTURER_NAME> must contain at least the following:

include(CMakeDependentOption)
string(TOLOWER ${QUL_PLATFORM} board_name)
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/${board_name})

You can also copy the contents of the example-baremetal platform to use as a reference.

Note: While all supported platforms have either baremetal or freertos appended to their names, the platform need not have either of them in its name.

Project structure

Qt Quick Ultralite does not have a strict structure that you have to follow. However, some things must be present and configured for the platform to be able to compile with Qt Quick Ultralite's CMake scripts.

cmake directory

Your project must have a cmake directory containing compiler and board information for Qt Quick Ultralite to be able to recognize and compile the platform. You may use the platform\boards\qt\example-baremetal\cmake directory as the basis for your platform's cmake directory. Note that example-baremetal project's cmake directory contains configuration for ARM GCC compiler and IAR compiler. If you are using a compiler other than ARM GCC, Green Hills, or IAR compilers, additional configuration is needed. For more information, see Using a custom toolchain.

The cmake directory has a following structure:

<YOUR_PLATFORM>
|-cmake
| |-<YOUR_COMPILER>
| | |-platform.cmake
| | |-BSPConfig.cmake
| | |-<YOUR_PLATFORM>.json
| | |-<YOUR_LINKER_SCRIPT>
| |-BoardDefaults.cmake
Defining default variables for the platform

BoardDefaults.cmake is used to set default variables for the platform port. For Qt Quick Ultralite, following variables can be set here:

VariableDecription
QUL_PLATFORM_ARCHITECTUREThe CPU architecture to use for your board. You can check platform\architecture for default ones. For custom architectures that are not included in the default ones see Architecture and Platform-specific Build Settings.
QUL_COLOR_DEPTHHow many bits per pixel is used to render content. This variable is optional and does not do anything if not used in the code.
QUL_PLATFORM_REQUIRED_IMAGE_ALIGNMENTThe minimum alignment required for image data on the given platform. See QUL_PLATFORM_REQUIRED_IMAGE_ALIGNMENT for details.
QUL_PLATFORM_REQUIRED_PIXEL_WIDTH_ALIGNMENTThe image width will be a multiple of this value on the given platform. See QUL_PLATFORM_REQUIRED_PIXEL_WIDTH_ALIGNMENT for details.
QUL_PLATFORM_DEFAULT_TEXT_CACHE_ENABLEDThe default value of text cache enable flag on the given platform. See QUL_PLATFORM_DEFAULT_TEXT_CACHE_ENABLED for details.
QUL_PLATFORM_DEFAULT_TEXT_CACHE_SIZEThe default value of text cache size on the given platform. See QUL_PLATFORM_DEFAULT_TEXT_CACHE_SIZE for details.
QUL_PLATFORM_DEFAULT_NUM_FRAMES_TO_PRESERVE_ASSETSThe default value of number of frame to preserve assets on the given platform. See QUL_PLATFORM_DEFAULT_NUM_FRAMES_TO_PRESERVE_ASSETS for details.
QUL_PLATFORM_DEFAULT_SCREEN_WIDTHThe default screen width in pixels. Not setting this will result in an error.
QUL_PLATFORM_DEFAULT_SCREEN_HEIGHTThe default screen height in pixels. Not setting this will result in an error.
QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_ALPHAThe default pixel format for transparent image resources. Not setting this will result in an error. See QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_ALPHA for details.
QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_OPAQUEThe default pixel format for opaque image resources. Not setting this will result in an error. See QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_OPAQUE for details.
QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_ALPHAThe default pixel format for lossless compression of transparent image resources. See QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_ALPHA for details.
QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_OPAQUEThe default pixel format for lossless compression of opaque image resources. See QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_OPAQUE for details.
QUL_PLATFORM_DEFAULT_RESOURCE_ALPHA_OPTIONSThe default setting of when to use ARGB32_Premultiplied format for the image resources. If this value is not set, Qt Quick Ultralite defaults to "ForTransformations". See QUL_PLATFORM_RESOURCE_ALPHA_OPTIONS for the details.
QUL_PLATFORM_DEFAULT_RESOURCE_RLE_PREMULTIPLIED_ALPHAThe default setting of when to use premultiplied alpha format for the alpha image resources using RLE compression. If this value is not set, Qt Quick Ultralite defaults to "On", i.e. premultiplied alpha. It's only necessary to change this if wanting to handle the Qul::PixelFormat_RLE_ARGB32 pixel format in the Qul::PlatformInterface::DrawingEngine::blendImage overload. By default the CPU fallback will be used, which requires premultiplied alpha. See QUL_PLATFORM_RESOURCE_RLE_PREMULTIPLIED_ALPHA for the details.
QUL_OSOperating system that is used in the project, used by app_common. Currently only BareMetal and FreeRTOS values are recognized. If this value is not set, Qt Quick Ultralite defaults to BareMetal. If you do not use app_common, this variable has no effect.
QUL_PLATFORM_EXCLUDED_EXAMPLESList of examples that are excluded from the build.

The following example disables freertos_multitask and image_cache examples:

set(QUL_PLATFORM_EXCLUDED_EXAMPLES
    "freertos_multitask"
    "image_cache"
    CACHE STRING "List of examples excluded from build")
QUL_PLATFORM_EXCLUDED_DEMOSList of demos that are excluded from the build.

The following example disables automotive and motor_cluster demos:

set(QUL_PLATFORM_EXCLUDED_DEMOS
    "automotive"
    "motor_cluster"
    CACHE STRING "List of demos excluded from build")

Example BoardDefaults.cmake:

IF(NOT QUL_COLOR_DEPTH)
    SET(QUL_COLOR_DEPTH 16)
ENDIF()
if(NOT QUL_PLATFORM_DEFAULT_SCREEN_WIDTH)
    set(QUL_PLATFORM_DEFAULT_SCREEN_WIDTH 480)
endif()
if(NOT QUL_PLATFORM_DEFAULT_SCREEN_HEIGHT)
    set(QUL_PLATFORM_DEFAULT_SCREEN_HEIGHT 272)
endif()
if(NOT QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_ALPHA)
    set(QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_ALPHA ARGB8888)
endif()
if(NOT QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_OPAQUE)
    set(QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_OPAQUE RGB565)
endif()

set (QUL_PLATFORM_ARCHITECTURE "cortex-m7-hf-fpv5-d16")

platform.cmake contains compile and link options specific to your platform. Architecture options can be found in the files for the specific architecture.

Specifying vendor SDK specific settings

BSPConfig.cmake contains all settings that are required for using functions from the vendor SDK, like GPIO or interrupt handlers.

See Platform SDK Config.

These usually are defines for a specific board and include paths.

target_compile_definitions(PlatformBSPConfig INTERFACE
    # Platform SDK specific compile definitions
    USE_HAL_DRIVER
)

target_include_directories(PlatformBSPConfig INTERFACE
    # Platform SDK specific include directories
    ${QUL_BOARD_SDK_DIR}/Projects/STM32F769I-Discovery/Templates/Inc/
    ${QUL_BOARD_SDK_DIR}/Drivers/BSP/STM32F769I-Discovery/
)
Creating the platform kit configuration file

<YOUR_PLATFORM>.json file is used to create a platform kit in the Qt Creator IDE.

Note: This file is only required if you are going to use the Qt Creator IDE.

Note: Custom compilers are not supported in Qt Creator.

The JSON file contains an object with values that are used by Qt Creator to create the kit:

AttributeDescription
qulVersionQt Quick Ultralite version the platform is built against. By default, this is set to @CMAKE_PROJECT_VERSION@.
platformName of the platform.
platformVendorName of the platform vendor/manufacturer.
colorDepthsList of supported color depths for the platform.
toolchainObject containing details of the toolchain the platform uses.
boardSdkObject containing details of the SDK the platform uses.

toolchain attribute contains the following information:

AttributeDescription
idName of the toolchain.
versionsList of toolchain versions that are supported.
cmakeToolchainFileLocation of the toolchain's CMake file.

boardSdk attribute contains the following information:

AttributeDescription
versionsList of SDK versions that are supported.

Here is an example JSON file (example-baremetal.json):

{
  "qulVersion": "@CMAKE_PROJECT_VERSION@",
  "compatVersion": "@COMPATIBILITY_VERSION@",
  "platform": {
    "colorDepths": [
      16
    ],
    "id": "EXAMPLE-BAREMETAL",
    "vendor": "Vendor Name",
    "pathEntries": [
      {
        "id": "EXAMPLE_PROGRAMMER_TOOL",
        "description": "Programmer Tool",
        "type": "path",
        "optional": false
      }
    ],
    "environmentEntries": [],
    "cmakeCacheEntries": [
      {
        "id": "Qul_DIR",
        "description": "Qt for MCUs SDK",
        "type": "path",
        "cmakeOptionName": "Qul_ROOT",
        "optional": false
      }
    ]
  },
  "toolchain": {
    "id": "armgcc",
    "versions": [
      "9.3.1"
    ],
    "cmakeCacheEntries": [
      {
        "id": "ARMGCC_DIR",
        "description": "GNU Arm Embedded Toolchain",
        "cmakeOptionName": "QUL_TARGET_TOOLCHAIN_DIR",
        "type": "path",
        "optional": false
      },
      {
        "id": "ARMGCC_CMAKE_TOOLCHAIN_FILE",
        "description": "CMake Toolchain File",
        "cmakeOptionName": "CMAKE_TOOLCHAIN_FILE",
        "type": "file",
        "defaultValue": "$Qul_ROOT/lib/cmake/Qul/toolchain/armgcc.cmake",
        "visible": false,
        "optional": false
      }
    ]
  },
  "boardSdk": {
    "versions": [
      "1.16.0"
    ],
    "cmakeCacheEntries": [
      {
        "id": "EXAMPLE_SDK_DIR",
        "description": "Board SDK",
        "cmakeOptionName": "QUL_BOARD_SDK_DIR",
        "type": "path",
        "optional": false
      }
    ]
  }
}

Here is the JSON file for the IAR compiler. It has a few differences compared to the previous example:

{
  "qulVersion": "@CMAKE_PROJECT_VERSION@",
  "compatVersion": "@COMPATIBILITY_VERSION@",
  "platform": {
    "id": "EXAMPLE-BAREMETAL",
    "vendor": "Vendor Name",
    "colorDepths": [
      16
    ],
    "pathEntries": [
      {
        "id": "EXAMPLE_PROGRAMMER_TOOL",
        "description": "Programmer Tool",
        "type": "path",
        "optional": false
      }
    ],
    "environmentEntries": [],
    "cmakeCacheEntries": [
      {
        "id": "Qul_DIR",
        "description": "Qt for MCUs SDK",
        "type": "path",
        "cmakeOptionName": "Qul_ROOT",
        "optional": false
      }
    ]
  },
  "toolchain": {
    "id": "iar",
    "versions": [
      "8.50.9"
    ],
    "cmakeCacheEntries": [
      {
        "id": "IAR_DIR",
        "description": "IAR ARM Compiler",
        "cmakeOptionName": "QUL_TARGET_TOOLCHAIN_DIR",
        "type": "path",
        "optional": false
      },
      {
        "id": "IAR_CMAKE_TOOLCHAIN_FILE",
        "description": "CMake Toolchain File",
        "cmakeOptionName": "CMAKE_TOOLCHAIN_FILE",
        "type": "file",
        "defaultValue": "$Qul_ROOT/lib/cmake/Qul/toolchain/iar.cmake",
        "visible": false,
        "optional": false
      }
    ]
  },
  "boardSdk": {
    "versions": [
      "1.16.0"
    ],
    "cmakeCacheEntries": [
      {
        "id": "EXAMPLE_SDK_DIR",
        "description": "Board SDK",
        "cmakeOptionName": "QUL_BOARD_SDK_DIR",
        "type": "path",
        "optional": false
      }
    ]
  }
}
Adding your linker script

cmake\<YOUR_COMPILER>\<YOUR_LINKER_SCRIPT> is the linker script your platform uses. Qt Quick Ultralite uses the linker script to organize the data and code in the final binary to appropriate memory addresses. Setting up of the script is described in detail with an example in the Linker script setup section.

Adding your linker script to the project

A default linker script can be set in BoardDefaults.cmake to be used by CMake. example-baremetal platform:

if(IAR)
    qul_platform_add_default_linker_script("${CMAKE_CURRENT_LIST_DIR}/${QUL_COMPILER_NAME}/example-platform.icf")
else()
    qul_platform_add_default_linker_script("${CMAKE_CURRENT_LIST_DIR}/${QUL_COMPILER_NAME}/example-platform.ld")
endif()

The argument defines the linker script to use. For more information, see Using a custom toolchain.

Creating the configuration file for you platform

platform\<YOUR_PLATFORM>\CMakeLists.txt is your platform's primary configuration file. It specifies all sources, include directories, compile definitions, and other parameters your platform requires. For more information about the CMake syntax, see CMake Documentation. You can also use platform\boards\qt\example-baremetal\CMakeLists.txt as a basis for your platform's CMakeLists.txt.

Note: When you are defining sources, include directories or other attributes for your platform, you must specify Platform as the target for these definitions.

The following is the CMakeLists.txt for the example-baremetal platform:

target_sources(Platform PRIVATE
    examplelayerengine.cpp
    examplepath.cpp
    examplestroker.cpp
    examplequeue.cpp
    platform.cpp
    mem.cpp
    ${PLATFORM_COMMON_SRC_DIR}/singlepointtoucheventdispatcher.cpp
    ${PLATFORM_COMMON_SRC_DIR}/platform.cpp
    # Add platform source files here
)

target_include_directories(Platform PRIVATE
    # Add platform specific include directories here
)

target_compile_definitions(Platform PRIVATE
    # Insert platform specific compile flags here
    # e.g. APPLICATION_ADDRESS=0x90000000
)

For IAR compiler, use the following example as a reference:

target_sources(Platform PRIVATE
    examplelayerengine.cpp
    examplepath.cpp
    examplestroker.cpp
    examplequeue.cpp
    platform.cpp
    mem-iar.cpp
    ${PLATFORM_COMMON_SRC_DIR}/singlepointtoucheventdispatcher.cpp
    ${PLATFORM_COMMON_SRC_DIR}/platform.cpp
    # Add platform source files here
)

target_include_directories(Platform PRIVATE
    # Add platform specific include directories here
)

target_compile_definitions(Platform PRIVATE
    # Insert platform specific compile flags here
    # e.g. APPLICATION_ADDRESS=0x90000000
)

The example CMakeLists.txt has two files defined in sources: platform.cpp and mem.cpp. These files contain sample code for basic functions and memory allocation API respectively. The contents of these files are documented in Implementing basic functions and Memory allocation in Qt Quick Ultralite platform abstraction chapters.

Creating flash targets

Qt Quick Ultralite CMake scripts offer support to generate targets for flashing binaries to the device. This is useful in the application development phase, where you might have to build and flash the binaries often. It offers a single command to build and flash the binary.

The following must be done in order to get flash targets generated:

  1. Create a new file called ExecutableHook.cmake under the platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake directory.
  2. Add the following function to ExecutableHook.cmake:
    function(add_executable_hook name)
        add_custom_target("flash_${name}" COMMAND <COMMAND_FOR_YOUR_FLASHER>)
        message(STATUS "Added flash target flash_${name}")
    endfunction()

    The name argument is the target application's name. For minimal example, name would be minimal and the resulting flash target is flash_minimal. <COMMAND_FOR_YOUR_FLASHER> is the command you use to flash built binaries to the target device. Your binary can be found using $<TARGET_FILE_DIR:${name}>/${name}.elf. Depending on the compiler and the flashing tool, the generated binary might be in a format that is not ELF.

Running CMake for your platform should now output Added flash target flash_<EXAMPLE/DEMO>. If you've copied example-baremetal project, you can use the following command to test whether flashing runs your flasher correctly:

nmake flash_minimal

However, your platform is still quite barebones. If your build does not succeed, continue reading this guide and try again at a later time.

Linker script setup

Linker script is a file containing information about the platform's memory configuration. It also specifies regions where application code and data resides. The the linker script is used by the toolchain's linker to organize the data and code in the final binary at appropriate memory addresses. In this section, you will get to know what needs to be configured in your linker script to get Qt Quick Ultralite working.

Following examples are snippets from platform\boards\qt\example-baremetal\cmake\armgcc\example-platform.ld. There is also a variant for IAR linkers available at platform\boards\qt\example-baremetal\cmake\iar\example-platform.icf for your reference. You can copy these files to your project to use as a basis for your own linker script. However, it is recommended that you have your own linker script where you insert additional memory sections explained here.

Note: The examples use GNU linker script syntax. Some things may be implemented differently between different toolchain linker scripts. Refer your toolchain's manual for more information about the syntax for linker scripts.

In order to assign program sections to the device, its memory layout must be configured:

MEMORY
{
  FLASH (rx)               : ORIGIN = 0x08000000, LENGTH = 2048K /* internal flash */
  RAM (xrw)                : ORIGIN = 0x20000000, LENGTH = 512K /* internal sram */
  SDRAM (xrw)              : ORIGIN = 0xc0400000, LENGTH = 6M /* external sdram memory */
  SDRAM_PRELOAD (xrw)      : ORIGIN = 0xc0a00000, LENGTH = 2M /* external sdram memory - preload */
  QSPI (rx)                : ORIGIN = 0x90000000, LENGTH = 64M /* external flash */
}

This layout has five regions: FLASH, RAM, SDRAM, SDRAM_PRELOAD and QSPI. RAM, SDRAM and SDRAM_PRELOAD have execute, read, and write access. Whereas, FLASH and QSPI are read-only flash memories and thus have only read and execute access.

Note: Avoid using this layout as-is for your platform's memory layout, as it may lead to errors when flashing the binary or attempting to run it on the device. Refer your target platform's manual for the memory layout and appropriate memory addresses for your device.

In this example resource data is stored in the QSPI flash memory region. QulResourceData name is hardcoded and represents the default section for the image resources. For adding additional resource sections see Managing Resources.

QulFontResourceData name is hardcoded and represents the default section for the font files and glyph data. Custom font files section is configured with QUL_FONT_FILES_RESOURCE_STORAGE_SECTION property and glyphs section with QUL_GLYPHS_RESOURCE_STORAGE_SECTION.

The QulModuleResourceData section is reserved by Qt Quick Ultralite to place its internal resources. User-specified resources should not be placed in it.

    QulFontResourceData :
    {
        . = ALIGN(4);
        *(QulFontResourceData)
    } > QSPI

    QulModuleResourceData :
    {
        . = ALIGN(4);
        __ModuleResourceDataCacheStart = .;
        *(QulModuleResourceData)
        . = ALIGN(4);
        __ModuleResourceDataCacheEnd = .;
    } > SDRAM AT> QSPI

    __ModuleResourceDataStart = LOADADDR(QulModuleResourceData);

    QulResourceData :
    {
        . = ALIGN(4);
        *(QulResourceData)
    } > QSPI

This example reserves space from the SDRAM for the preloadable resources with SDRAM_PRELOAD region. Symbols __preloadSdramStart and __preloadSdramEnd are defined for the resource preloading to determine the start and end address of the preload section:

    __preloadSdramStart = ORIGIN(SDRAM_PRELOAD);
    __preloadSdramEnd = ORIGIN(SDRAM_PRELOAD) + LENGTH(SDRAM_PRELOAD);

Example platform adaptation creates pointers to the linker symbols:

extern uint8_t __preloadSdramStart;
extern uint8_t __preloadSdramEnd;
void *preloadSdramStart = &__preloadSdramStart;
void *preloadSdramEnd = &__preloadSdramEnd;

By default the resources use DefaultPreload allocation type. Preload start and end address are used by the ExampleReversePreloadAllocator to determine the maximum size of the preload section.

PlatformInterface::MemoryAllocator *ExamplePlatform::memoryAllocator(
    PlatformInterface::MemoryAllocator::AllocationType type)
{
    static ExampleMemoryAllocator exampleMemoryAllocator;
    static ExampleReversePreloadAllocator<4> examplePreloadAllocator(preloadSdramEnd, preloadSdramStart);
    static PlatformInterface::MemoryAllocator defaultMemoryAllocator;

    switch (type) {
    case PlatformInterface::MemoryAllocator::Image:
        return &exampleMemoryAllocator;
    case PlatformInterface::MemoryAllocator::DefaultPreload:
        return &examplePreloadAllocator;
    default:
        return &defaultMemoryAllocator;
    }
}

Preloading can be disabled by returning nullptr from the memory allocator for the DefaultPreload allocation type.

Preloading Qt Quick Ultralite internal resources

Qt Quick Ultralite internal resources contain the image data for example for the dials and buttons that are linked to the application from Qul::Controls library. Internal resources do not support preloading with Qul::PlatformInterface::MemoryAllocator.

In this example preloadable internal resource data is copied from the QSPI flash memory region to SDRAM.

__ModuleResourceDataCacheStart, __ModuleResourceDataCacheEnd, and __ModuleResourceDataStart must also be defined. They are used in the platform code to load the resources from QSPI to SDRAM:

extern unsigned char __ModuleResourceDataStart;
extern unsigned char __ModuleResourceDataCacheStart;
extern unsigned char __ModuleResourceDataCacheEnd;
memcpy(&__ModuleResourceDataCacheStart,
       &__ModuleResourceDataStart,
       &__ModuleResourceDataCacheEnd - &__ModuleResourceDataCacheStart);

For IAR compilers there need to be some section declarations included

#pragma section = "QulModuleResourceData"
#pragma section = "QulModuleResourceData_init"
char *__ModuleResourceDataStart = (char *) (__section_begin("QulModuleResourceData_init"));
char *__ModuleResourceDataCacheStart = (char *) (__section_begin("QulModuleResourceData"));
char *__ModuleResourceDataCacheEnd = (char *) (__section_end("QulModuleResourceData"));
memcpy(__ModuleResourceDataCacheStart,
       __ModuleResourceDataStart,
       (unsigned) __ModuleResourceDataCacheEnd - (unsigned) __ModuleResourceDataCacheStart);

Make sure to check the example IAR linker script to see how to place these sections in your device memory.

Note: If preloading is not used, QulModuleResourceData can be added to the linker script in the same way as QulResourceData. In this case __ModuleResourceData* symbols and memcpy are not needed.

Using a custom toolchain

By default, Qt Quick Ultralite supports ARM GCC, GHS, or IAR toolchains across the supported platforms. However, it is possible to use your own compiler in the project.

To configure Qt Quick Ultralite for your toolchain, follow these steps:

  1. Add a <YOUR_COMPILER>.cmake to lib\cmake\Qul\toolchain directory.
  2. Create <YOUR_COMPILER> directory under platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake.
  3. Edit CMake configuration files in Qt Quick Ultralite

Adding <YOUR_COMPILER>.cmake to the project

Add the <YOUR_COMPILER>.cmake to the lib\cmake\Qul\toolchain directory. This file configures your toolchain for the project. You can also use existing toolchain configurations as a basis for your compiler configuration.

The following variables should be set in the file:

VariableDescription
CMAKE_SYSTEM_NAMEThe operating system CMake is building for. This must be set to Generic.
CMAKE_SYSTEM_PROCESSORThe processor CMake is building for. For example, if your target CPU is ARM CPU, set this to arm.
COMPILER_FOLDER_NAMETells Qt Quick Ultralite project what compiler directory should be used for the target platform. This must match the name of the compiler directory in platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake or else you will get errors during configuration.
LINKER_SCRIPT_OPTIONThis is used in qul_platform_add_default_linker_script to tell linker what flags to use. If you are not using LINKER_SCRIPT_OPTION, this is not needed.
CMAKE_C_COMPILERPath to the C compiler.
CMAKE_CXX_COMPILERPath to the C++ compiler.
CMAKE_ASM_COMPILERPath to the assembly compiler. This is not needed if you do not have assembly files in you platform.
CMAKE_ARPath to the toolchain's archiver.
CMAKE_CXX_FLAGS_INITC++ compiler flags that are used in every configuration.
CMAKE_C_FLAGS_INITC compiler flags that are used in every configuration.
CMAKE_C_FLAGS_DEBUGC compiler flags that are used in debug configuration in addition to the flags used in CMAKE_C_FLAGS_INIT.
CMAKE_CXX_FLAGS_DEBUGC++ compiler flags that are used in debug configuration in addition to the flags used in CMAKE_CXX_FLAGS_INIT.
CMAKE_EXE_LINKER_FLAGS_INITLinker flags that are used in every configuration.

In addition, you also need to set a variable that can be used to identify your compiler:

SET(<YOUR_COMPILER> ON)

This is used in other CMake files to configure additional things if needed.

<YOUR_COMPILER> directory

Create a directory named <YOUR_COMPILER> (or the name you set to COMPILE_FOLDER_NAME in the previous step) for your toolchain in the platform\boards\<MANUFACTURER_NAME>\<YOUR_PLATFORM>\cmake directory, and add all required files mentioned in the "cmake directory" section.

CMake configuration files in Qt Quick Ultralite

Your toolchain may require some additional configuration in Qt Quick Ultralite.

The following files contain compiler-dependent configurations and might be worth checking out.

  • examples\CMakeLists.txt has compiler-dependent warning flags, such as Wall and Werror. If your compiler does not support already provided flags, add your own here.
  • platform\CMakeLists.txt If you are going to use same compiler on multiple platforms, it might be a good idea to write some common compilation options for Platform here.
  • src\CMakeLists.txt is used to build Core target. If your compiler has some specific arguments that must be taken into account, add them here.

    The file also includes configuration code for supported compilers. Check that your compiler can use the set parameters and modify the code if needed.

  • src\pngdecoders.cmake adds LodePNG based PNG decoder to Qt Quick Ultralite. If your compiler has some specific arguments that must be taken into account when building the decoder, add them here.

Your compiler setup is ready to be used now. Test it by running CMake with -DCMAKE_TOOLCHAIN_FILE=path\to\Qt\QtMCUs\1.5.0\cmake\Qul\toolchain\<YOUR_COMPILER>.cmake.

Available under certain Qt licenses.
Find out more.