Getting started Creating the platform configuration file

C

Creating the platform kit configuration file

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

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.

Main elements of the kit's JSON file are:

Attribute	Description
`qulVersion`	Qt Quick Ultralite version the platform is built against. By default, this is set to `@CMAKE_PROJECT_VERSION@`.
`platform`	Object containing the platform's name, a list of supported color depths, the vendor/manufacturer name and 3rd party packages.
`toolchain`	Object containing the details about the toolchain that the platform uses. This is split into two objects - compiler and file. The former helps finding the compiler and the latter contains the location of the toolchain's CMake file Using a custom toolchain.
`boardSdk`	Object containing details of the SDK the platform uses.
`freeRTOS`	Object containing details of the FreeRTOS support of the platform. This part is not present in baremetal devices.

The JSON file contains a collection of json objects used by Qt Creator to create the kit. Each object represents a 3rd party dependency (package) and holds a path to the dependency. The path will later be forwarded to different outputs:

A cmake variable used to configure the project (e.g. -DFREERTOS_DIR=<path>)
A directory that will be added to PATH environment variable

The package value can be read by QtCreator from the folowing locations, in order:

Qt Creator settings.
The correspoding Environmental variable (envVar).
The defaultValue defined in the json file.

In summary the packages required for a correct kit to be generated are:

Platform's 3rd party packages (cmakeEntries array).
The toolchain packages (a compiler and a toolchain file).
BoardSdk package
FreeRTOS package (when applicable)

Each package has the following attributes:

Attribute	Description
`cmakeVar`	Output cmake variable
`setting`	QtCreator setting name which should be set by Qt Online Installer.
`envVar`	Environment variable name to override value from settings.
`label`	Label shown in UI of the MCU support plugin (Edit -> Preferences -> Devices -> MCU)
`defaultValue`	Default value that is used when setting or environment variable is not set. Split into separate values for windows and linux.
`versions`	List of versions that are supported.
`versionDetection`	Information used for version detection.
`validation`	Path suffix used to validate the package.

The platform json kit file can be validated using a schema file found in $QUL_ROOT/kits/schemas/ and a jsonschema validation tool of choice, an online solution can be found here. The schemas are using the Draft-2020-12 specification. Currently only "schema-2.3" is provided to validate kits that works with QtMCUs 2.3.0 and higher.

Main elements of the kit's JSON file are: 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"
    },
    "toolchain": {
        "id": "armgcc",
        "versions": [
            "10.3.1"
        ],
        "compiler": {
            "id": "ARMGCC_DIR",
            "label": "GNU Arm Embedded Toolchain",
            "cmakeVar": "QUL_TARGET_TOOLCHAIN_DIR",
            "envVar": "ARMGCC_DIR",
            "setting": "GNUArmEmbeddedToolchain",
            "type": "path",
            "optional": false,
            "versionDetection": {
                "filePattern": {
                    "windows": "bin/arm-none-eabi-g++.exe",
                    "linux": "bin/arm-none-eabi-g++"
                },
                "executableArgs": "--version",
                "regex": "\\b(\\d+\\.\\d+\\.\\d+)\\b"
            },
            "detectionPath": {
                "windows": "bin/arm-none-eabi-g++.exe",
                "linux": "bin/arm-none-eabi-g++"
            }
        },
        "file": {
            "id": "ARMGCC_CMAKE_TOOLCHAIN_FILE",
            "cmakeVar": "CMAKE_TOOLCHAIN_FILE",
            "type": "file",
            "defaultValue": "%{Qul_ROOT}//lib/cmake/Qul/toolchain/armgcc.cmake",
            "visible": false,
            "optional": false
        }
    },
    "boardSdk": {
        "versions": [
            "1.16.0"
        ],
        "id": "EXAMPLE_SDK_DIR",
        "label": "Board SDK",
        "cmakeVar": "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
        ]
    },
    "toolchain": {
        "id": "iar",
        "versions": [
            "9.20.4"
        ],
        "compiler": {
            "id": "IARToolchain",
            "setting": "IARToolchain",
            "envVar": "IAR_ARM_COMPILER_DIR",
            "label": "IAR ARM Compiler",
            "cmakeVar": "QUL_TARGET_TOOLCHAIN_DIR",
            "type": "path",
            "versionDetection": {
                "filePattern": {
                    "windows": "bin/iccarm.exe",
                    "linux": "bin/iccarm"
                },
                "executableArgs": "--version",
                "regex": "\\bV(\\d+\\.\\d+\\.\\d+)\\.\\d+\\b"
            },
            "detectionPath": {
                "windows": "bin/iccarm.exe",
                "linux": "bin/iccarm"
            },
            "defaultValue": {
                "windows": "%{Env:PROGRAMFILES}/IAR Systems/Embedded Workbench 9.0/arm",
                "linux": "/opt/iarsystems/bxarm-9.20.4/arm"
            },
            "optional": false
        },
        "file": {
            "id": "IAR_CMAKE_TOOLCHAIN_FILE",
            "cmakeVar": "CMAKE_TOOLCHAIN_FILE",
            "type": "file",
            "defaultValue": "%{Qul_ROOT}/lib/cmake/Qul/toolchain/iar.cmake",
            "visible": false,
            "optional": false
        }
    },
    "boardSdk": {
        "versions": [
            "1.16.0"
        ],
        "id": "EXAMPLE_SDK_DIR",
        "label": "Board SDK",
        "cmakeVar": "QUL_BOARD_SDK_DIR",
        "type": "path",
        "optional": false
    }
}

Getting started Creating the platform configuration file

Available under certain Qt licenses.
Find out more.