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> should be lower case names to avoid issues.
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 platform configuration file. The one under <MANUFACTURER_NAME> must contain at least the following:
include(CMakeDependentOption)
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/${QUL_PLATFORM})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 | | |-<YOUR_PLATFORM>.json | | |-<YOUR_LINKER_SCRIPT> | |-BoardArchitectureConfig.cmake | |-BoardDefaults.qmlprojectconfig | |-BSPConfig.cmake | |-LinkerScriptConfig.cmake
Defining default variables for the platform
As shown above, default variables for a platform are organized in the following way:
BoardDefaults.qmlprojectconfigcontains Qt Quick Ultralite engine-specific configurations the target board. See QmlProject Manual for more information.BoardArchitectureConfig.cmakecontains information about the platform architecture.LinkerScriptConfig.cmakecontains linker script configurations. See Adding your linker script.- Platform-specific configurations were moved to the platform
CMakeLists.txtfile. See Setting platform properties
BoardDefaults.qmlprojectconfig naming scheme
A platform port can have more than one BoardDefaults.qmlprojectconfig file depending on different board or display configurations. To be able to support all those configurations, use the following naming convention:
BoardDefaults_<color_depth>bpp_<default>.qmlprojectconfig
where:
- The
color_depthvalue should be set to the QUL_COLOR_DEPTH CMake variable. This value is used also to determine the span of available configurations based on multiple qmlprojectconfig files existing in the platform cmake directory. - If there are multiple configurations, use the
defaultkeyword for one of them to indicate a default configuration.
The following table describes different example scenarios and the corresponding configuration file name:
| Scenario | Behavior |
|---|---|
Only one BoardDefaults.qmlprojectconfig file exists.cmake |- BoardDefaults.qmlprojectconfig | In a scenario like this where color_depth information is not part of the file name, explicitly provide the QUL_COLOR_DEPTH option to the CMake command. |
Only one BoardDefaults_<color_depth>.qmlprojectconfig file exist.cmake |- BoardDefaults_32bpp.qmlprojectconfig | When using configurations that include the color_depth information in the file name, there is no need to provide the -DQUL_COLOR_DEPTH option to the CMake command. |
Multiple BoardDefaults_<color_depth>.qmlprojectconfig files exist. Non of it uses default keyword.cmake |- BoardDefaults_8bpp.qmlprojectconfig |- BoardDefaults_16bpp.qmlprojectconfig |- BoardDefaults_32bpp.qmlprojectconfig | In this scenario where multiple qmlprojectconfig files include the color_depth information in the file name then explicitly provide the QUL_COLOR_DEPTH option to the CMake command. |
Multiple BoardDefaults_<color_depth>.qmlprojectconfig files exist. One of it contains default keyword.cmake |- BoardDefaults_8bpp_default.qmlprojectconfig |- BoardDefaults_16bpp.qmlprojectconfig |- BoardDefaults_32bpp.qmlprojectconfig | When one of the configurations contains the default keyword in the file name, it will be picked automatically. To choose a different one explicitly provide the QUL_COLOR_DEPTH option to the CMake command. |
Note: If the qmlprojectconfig file is not named according to the convention, explicitly provide the -DQUL_PLATFORM_BOARD_DEFAULTS_QMLPROJECTCONFIG=<path_to_qmlprojectconfig_file> option to the CMake command.
Available under certain Qt licenses.
Find out more.
