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:

AttributeDescription
qulVersionQt Quick Ultralite version the platform is built against. By default, this is set to @CMAKE_PROJECT_VERSION@.
platformObject containing the platform's name, a list of supported color depths, the vendor/manufacturer name and 3rd party packages.
toolchainObject 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.
boardSdkObject containing details of the SDK the platform uses.
freeRTOSObject 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:

AttributeDescription
cmakeVarOutput cmake variable
settingQtCreator setting name which should be set by Qt Online Installer.
envVarEnvironment variable name to override value from settings.
labelLabel shown in UI of the MCU support plugin (Edit -> Preferences -> Devices -> MCU)
defaultValueDefault value that is used when setting or environment variable is not set. Split into separate values for windows and linux.
versionsList of versions that are supported.
versionDetectionInformation used for version detection.
validationPath 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
    }
}

Available under certain Qt licenses.
Find out more.