C

迁移指南到 QmlProject

描述

从 Qt Quick Ultralite 2.4 开始,QmlProject 文件(一个扩展名为 .qmlproject 的文件)描述了包含所有源代码、资源、模块和配置设置的工程。本指南描述了如何将现有的 Qt for MCUs 项目从 CMake 迁移到 QmlProject。在迁移现有项目时,将废弃的 CMake API 替换为 QmlProject 中的相应节点。有关 QmlProject API 的说明和使用方法,请参阅 QmlProject 手册。有关 CMake API 的更多信息,请参阅 CMake 手册

qmlprojectexporter 工具处理 .qmlproject 文件,并调用其他工具生成项目所需的源文件。它允许您独立于 CMake 定义您的 Qt for MCUs 项目。您还可以使用它与 CMake 结合,通过使用具有 QML_PROJECT 选项的 qul_add_target() 完成。此自定义 CMake 命令幕后调用 qmlprojectexporter。本指南中稍后提供的 CMakeLists.txt 示例说明了您如何使用 CMake 来实现这一点。

废弃的 CMake API 列表及其替代品

废弃的 CMake 变量

注意:带有 PLATFORM 前缀的变量适用于平台移植,它们的替代品属于平台的 BoardDefaults.qmlprojectconfig 文件。有关详细信息,请参阅 平台移植指南到 Qt for MCUs 2.3

废弃的 CMake 变量QmlProject 替代品描述
QUL_DEBUG_BYTECODEMCU.Config.debugBytecode将 JavaScript 字节码作为注释添加到生成的源代码中
QUL_DEBUG_LINE_DIRECTIVESMCU.Config.debugLineDirectives将 #line 指令添加到生成的源代码中。
QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_ALPHAMCU.Config.platformAlphaCompressedLosslessResourcePixelFormat定义透明图像资源的无损压缩默认格式。
QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_OPAQUEMCU.Config.platformOpaqueCompressedLosslessResourcePixelFormat不透明图像资源无损压缩的默认像素格式。
QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_ALPHAMCU.Config.platformAlphaPixelFormat透明图像资源的默认像素格式。
QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_OPAQUEMCU.Config.platformOpaquePixelFormat不透明图像资源的默认像素格式。
QUL_PLATFORM_REQUIRED_IMAGE_ALIGNMENTMCU.Config.platformImageAlignment在特定平台上对图像数据所需的最小对齐方式。
QUL_PLATFORM_REQUIRED_PIXEL_WIDTH_ALIGNMENTMCU.Config.platformPixelWidthAlignment图像宽度将为给定平台该值的倍数。

CMake目标属性,字体

已弃用的CMake目标属性QmlProject 替代品描述
QUL_FONT_FILESFontFiles.files字体文件路径列表。
QUL_AUTO_GENERATE_GLYPHSMCU.Config.autoGenerateGlyphs此选项控制静态字体引擎的自动字形生成。
QUL_COMPLEX_TEXT_RENDERINGMCU.Config.complexTextRendering启用复杂脚本的渲染。
QUL_DEFAULT_FONT_FAMILYMCU.Config.defaultFontFamily文本元素的默认字体家族。
QUL_DEFAULT_FONT_QUALITYMCU.Config.defaultFontQuality文本元素的默认字体质量。
QUL_FONT_CACHE_PREALLOCMCU.Config.fontCachePrealloc控制字体缓存缓冲区的预分配。
QUL_FONT_CACHE_PRIMINGMCU.Config.fontCachePriming启用字体缓存预读。
QUL_FONT_CACHE_SIZEMCU.Config.fontCacheSize设置字体引擎使用的最大缓存大小。
QUL_FONT_ENGINEMCU.Config.fontEngine启用提供的字体引擎。
QUL_FONT_FILES_RESOURCE_CACHE_POLICYMCU.Config.fontFilesCachePolicy配置应用程序字体文件的复制。
QUL_FONT_FILES_RESOURCE_RUNTIME_ALLOCATION_TYPEMCU.Config.fontFilesRuntimeAllocationType配置复制应用程序字体文件时使用的运行时分配类型。
QUL_FONT_FILES_RESOURCE_STORAGE_SECTIONMCU.Config.fontFilesStorageSection配置用于应用程序字体文件的资源存储部分。
QUL_FONT_HEAP_PREALLOCMCU.Config.fontHeapPrealloc控制字体引擎使用的堆缓冲区的预分配。
QUL_FONT_HEAP_SIZEMCU.Config.fontHeapSize设置字体引擎的最大堆大小。
QUL_FONT_VECTOR_OUTLINES_DRAWINGMCU.Config.fontVectorOutlinesDrawing用于文本渲染使用矢量轮廓。
QUL_GLYPHS_RESOURCE_CACHE_POLICYMCU.Config.glyphsCachePolicy配置将预光栅化字形数据复制到RAM以进行更快的访问。
QUL_GLYPHS_RESOURCE_RUNTIME_ALLOCATION_TYPEMCU.Config.glyphsRuntimeAllocationType配置复制预光栅化字形数据到RAM时使用的运行时分配类型。
QUL_GLYPHS_RESOURCE_STORAGE_SECTIONMCU.Config.glyphsStorageSection配置用于将预光栅化字形数据复制到RAM的资源存储部分。
QUL_MAX_PARAGRAPH_SIZEMCU.Config.maxParagraphSize设置最大段大小。
QUL_CONTROLS_STYLEMCU.Config.controlsStyle重写Controls样式。

已弃用图像源文件属性

已弃用的CMake命令

已弃用的CMake命令QmlProject 替代品描述
qul_add_qml_moduleModuleFiles (Node in <MainProject>.qmlproject)向项目中添加QML模块。该模块必须有自己的.qmlproject文件。
MCU.Module (Node in <module>.qmlproject)此节点将.qmlproject文件指定为模块的一部分,并定义其URI。
qul_add_resourceImageFiles (节点)向目标添加图像资源。
qul_set_maximum_resource_cache_sizeMCU.Config.maxResourceCacheSize (属性)设置给定运行时资源分配类型的最大资源缓存大小。
qul_target_embed_translationsTranslationFiles (节点)从.ts文件中嵌入翻译。
qul_target_generate_interfacesInterfaceFiles (节点)将导出的C++类公开给QML上下文。
qul_target_qml_sourcesQmlFiles (节点)向目标添加QML源文件。

迁移现有项目

要将项目迁移到Qt for MCUs 2.4或更高版本,需添加一个.qmlproject文件。此文件可以命名任意图,但本指南使用<MainProject>.qmlproject。您的项目CMakeLists.txt需要重大更改来删除对已弃用的CMake API的使用。其替代品位于.qmlproject文件中。

QML文件

已弃用的CMake命令QmlProject 替代品描述
qul_target_qml_sourcesQmlFiles (节点)向目标添加QML源文件。

负责向项目中添加QML源文件的QmlFiles节点。它在其files属性中接受源文件列表。该节点替代了qul_target_qml_sources()自定义CMake命令。在迁移到Qt for MCUs 2.4时,从CMake项目文件中删除对此的引用。

# DEPRECATED
qul_target_qml_sources(<target> WelcomeScreen.qml Menu.qml)

.qmlproject文件,即<MainProject>.qmlproject文件中,用以下内容替换CMakeLists.txt中的所有对qul_target_qml_source的引用

QmlFiles {
    files: [
        "WelcomeScreen.qml",
        "Menu.qml"
    ]
}

C++接口

已弃用的CMake命令QmlProject 替代品描述
qul_target_generate_interfacesInterfaceFiles (节点)将导出的C++类公开给QML上下文。

使用InterfaceFiles节点向项目中添加C++头文件,并生成在QML上下文中可访问的接口。其files属性接受C++头文件列表并将其添加到项目中。您还可以使用MCU.qmlImports属性添加接口所需的额外QML导入。

InterfaceFiles节点及其属性替代了已弃用的CMake命令qul_target_generate_interfaces()。在迁移到Qt for MCUs 2.4或更高版本时,从项目中删除对此命令的所有引用。

较旧的Qt for MCUs版本在CMakeLists.txt中触发接口生成

# DEPRECATED
qul_target_generate_interfaces(
    <target>
    interface1.h interface2.h
    QML_IMPORTS SomeQmlModule
)

在项目中的.qmlproject文件中将此CMake命令的所有实例替换为以下内容

InterfaceFiles {
    files: [
        "interface1.h",
        "interface2.h"
    ]
    MCU.qmlImports: ["SomeQmlModule"]
}

注意: qmlprojectexporter将生成的接口存储在输出目录中。QmlProject没有在qul_target_generate_interfaces()中的OUTPUT_DIRECTORY参数的替代品。

图像

已弃用的CMake命令QmlProject 替代品描述
qul_add_resourceImageFiles (节点)向目标添加图像资源。
已弃用的CMake源文件属性替换(ImageFiles属性)描述
QUL_RESOURCE_CACHE_POLICYMCU.resourceCachePolicy (属性)定义图像缓存策略。
QUL_RESOURCE_COMPRESSIONMCU.resourceCompression (属性)将图像以压缩格式存储。
QUL_RESOURCE_IMAGE_PIXEL_FORMATMCU.resourceImagePixelFormat (属性)设置图像的首选像素格式。
QUL_RESOURCE_OPTIMIZE_FOR_ROTATIONMCU.resourceOptimizeForRotation (属性)启用在运行时旋转图像的优化。
QUL_RESOURCE_OPTIMIZE_FOR_SCALEMCU.resourceOptimizeForScale (属性)启用在运行时缩放图像的优化。
QUL_RESOURCE_RUNTIME_ALLOCATION_TYPEMCU.resourceRuntimeAllocationType(属性)定义资产的运行时分配类型。
QUL_RESOURCE_STORAGE_SECTIONMCU.resourceStorageSection(属性)定义资产的存储部分。

使用ImageFiles节点将图像文件添加到项目中,并配置其属性。您可以在files属性下列出图像资产。如果需要更改这些资产的默认配置,请将其添加到添加资产的ImageFiles节点。此节点替换了qul_add_resource()set_source_files_properties() CMake API。

以下示例显示了项目CMakeLists.txt中使用的已弃用的CMake API。

# DEPRECATED
set_source_files_properties(
    img1.png
    img2.png
    PROPERTIES
        QUL_RESOURCE_COMPRESSION ON
)
set_source_files_properties(
    img2.png
    PROPERTIES
        QUL_RESOURCE_OPTIMIZE_FOR_ROTATION ON
)

# DEPRECATED
qul_add_resource(<target> FILES img1.png img2.png)

当迁移到Qt for MCUs 2.4或更高版本时,请在您的<MainProject>.qmlproject中使用两个ImageFiles节点替换这些API,一个用于每个属性配置集。

ImageFiles {
    files: ["img1.png"]
    MCU.resourceCompression: true
}

ImageFiles {
    files: ["img2.png"]
    MCU.resourceCompression: true
    MCU.resourceOptimizeForRotation: true
}

项目默认属性

可以在MCU.Config节点中定义一组图像属性的默认值。该值适用于项目添加的所有资源,除非在ImageFiles节点中明确覆盖。

以下示例使用较早章节中的示例说明如何默认启用resourceCompression。它使用MCU.Config节点,使其适用于项目中的所有资源。如果资源需要覆盖默认设置,则可以在添加资源的ImageFiles节点中执行此操作。最后的ImageFiles节点通过仅禁用"img3.png"资源的压缩来说明这一点。

以下示例说明如何使用MCU.Config节点设置项目级别的默认值。

MCU.Config {
    MCU.resourceCompression: true
}

ImageFiles {
    files: ["img1.png"]
}

ImageFiles {
    files: ["img2.png"]
    MCU.resourceOptimizeForRotation: true
}

ImageFiles {
    files: ["img3.png"]
    MCU.resourceCompression: false
}

字体

已弃用的CMake目标属性FontFiles属性描述
QUL_FONT_FILESfiles(属性)字体文件路径列表。
已弃用的CMake目标属性MCU.Config属性描述
QUL_AUTO_GENERATE_GLYPHSautoGenerateGlyphs(属性)此选项控制静态字体引擎的自动字形生成。
QUL_COMPLEX_TEXT_RENDERINGcomplexTextRendering(属性)启用复杂脚本的渲染。
QUL_CONTROLS_STYLEcontrolsStyle(属性)重写Controls样式。
QUL_DEFAULT_FONT_FAMILYdefaultFontFamily(属性)文本元素的默认字体家族。
QUL_DEFAULT_FONT_QUALITYdefaultFontQuality(属性)文本元素的默认字体质量。
QUL_FONT_CACHE_PREALLOCfontCachePrealloc(属性)控制字体缓存缓冲区的预分配。
QUL_FONT_CACHE_PRIMINGfontCachePriming(属性)启用字体缓存预读。
QUL_FONT_CACHE_SIZEfontCacheSize(属性)设置字体引擎使用的最大缓存大小。
QUL_FONT_ENGINEfontEngine(属性)启用提供的字体引擎。
QUL_FONT_FILES_RESOURCE_CACHE_POLICYfontFilesCachePolicy(属性)配置应用程序字体文件的复制。
QUL_FONT_FILES_RESOURCE_RUNTIME_ALLOCATION_TYPEfontFilesRuntimeAllocationType(属性)配置复制应用程序字体文件时使用的运行时分配类型。
QUL_FONT_FILES_RESOURCE_STORAGE_SECTIONfontFilesStorageSection(属性)配置用于应用程序字体文件的资源存储部分。
QUL_FONT_HEAP_PREALLOCfontHeapPrealloc(属性)控制字体引擎使用的堆缓冲区的预分配。
QUL_FONT_HEAP_SIZEfontHeapSize(属性)设置字体引擎的最大堆大小。
QUL_FONT_VECTOR_OUTLINES_DRAWINGfontVectorOutlinesDrawing(属性)用于文本渲染使用矢量轮廓。
QUL_GLYPHS_RESOURCE_CACHE_POLICYglyphsCachePolicy(属性)配置将预光栅化字形数据复制到RAM以进行更快的访问。
QUL_GLYPHS_RESOURCE_RUNTIME_ALLOCATION_TYPEglyphsRuntimeAllocationType(属性)配置复制预光栅化字形数据到RAM时使用的运行时分配类型。
QUL_GLYPHS_RESOURCE_STORAGE_SECTIONglyphsStorageSection(属性)配置用于将预光栅化字形数据复制到RAM的资源存储部分。
QUL_MAX_PARAGRAPH_SIZEmaxParagraphSize(属性)设置最大段大小。

您可以将字体文件添加到项目中,通过使用节点中的files属性。这个节点取代了QUL_FONT_FILES的CMake目标属性。您可以使用节点添加字体特定的配置,例如字体引擎的选择。早期列表中的所有字体属性都将替换为相应的CMake目标属性,在迁移到Qt for MCUs 2.4或更高版本时,应该从项目中移除这些属性。

# DEPRECATED
set_target_properties(<target>
    PROPERTIES
        QUL_FONT_FILES MyFont.ttf
        QUL_FONT_ENGINE Spark
        QUL_DEFAULT_FONT_FAMILY default
        QUL_MAX_PARAGRAPH_SIZE 80
)

需要使用两个不同的节点来在QmlProject中定义这个配置。

FontFiles {
    files: ["MyFont.ttf"]
}

MCU.Config {
    fontEngine: "Spark"
    defaultFontFamily: "default"
    maxParagraphSize: 80
}

注意:addDefaultFonts属性没有对应的CMake API。它允许您控制使用Qt for MCUs SDK中提供的默认字体。此属性默认为true。如果您不需要默认字体,请设置为false

模块

已弃用的CMake命令QmlProject 替代品描述
qul_add_qml_moduleModuleFiles (Node in <MainProject>.qmlproject)向项目中添加QML模块。该模块必须有自己的.qmlproject文件。
MCU.Module(在.qmlproject中的节点)此节点将.qmlproject文件指定为模块的一部分,并定义其URI。

自Qt for MCUs 2.4起,模块应该具有自己的.qmlproject文件。此文件与主项目的.qmlproject文件类似,但必须包含一个定义模块URI的节点的实例。如表中所示,.qmlproject中的节点和每个自定义模块的单独.qmlproject文件的组合取代了已弃用的CMake命令()。

将模块包含在主项目中

节点的files属性接受一个指向自定义模块.qmlproject文件的路径列表。

在Qt for MCUs的旧版本中,您可以使用qul_add_qml_module CMake API将模块添加到项目中。以下示例演示了如何操作

# DEPRECATED
qul_add_qml_module(
    <target>
    URI MyModule
    QML_FILES CustomComponent.qml
)

自Qt for MCUs 2.4起,您可以将模块添加到项目的.qmlproject文件中。以下示例演示了如何在.qmlproject中操作。

ModuleFiles {
    files: ["<Module>.qmlproject"]
}

创建自定义模块

模块的.qmlproject文件必须有一个定义模块URI的节点实例。除这个节点外,模块的.qmlproject文件与任何其他.qmlproject文件的工作方式相同。

以下片段是之前章节中使用的代码片段的完整内容,用于描述URI为MyModule的模块,该模块有一个名为CustomComponent.qml的单个QML文件。

import QmlProject 1.3

Project {
    MCU.Module {
        uri: "MyModule"
    }

    QmlFiles {
        files: ["CustomComponent.qml"]
    }
}

Qt Quick Ultralite模块

如果使用节点添加Qt for MCUs SDK中的模块,则需要从项目的CMakeLists.txt中删除相应的target_link_libraries()

节点具有MCU.qulModules属性,它期望一个字符串列表,指定要添加到项目中哪个模块。

ModuleFiles {
    MCU.qulModules: [
        "Controls",
        "ControlsTemplates",
        "Shapes",
        "Timeline"
    ]
}

注意:除了自定义模块外,您还可以使用一个 ModuleFiles 节点来链接到针对MCU的Qt模块。在同一个 ModuleFiles 节点中,可以结合添加自定义模块和针对MCU的Qt模块。

翻译

已弃用的CMake命令QmlProject 替代品描述
qul_target_embed_translationsTranslationFiles (节点)从.ts文件中嵌入翻译。

TranslationFiles 节点取代了已废弃的自定义CMake命令 qul_target_embed_translations()。当您移植到2.4或更高版本的Qt for MCUs时,请移除对该命令的所有引用。

此节点接受一个在 files 属性中的翻译文件(以 .ts 扩展名结尾)列表。布尔属性 MCU.omitSourceLanguage 允许您控制是否在应用程序中使用源语言。

CMakeLists.txt 使用废弃的命令

# DEPRECATED
qul_target_embed_translations(
    <target>
    translation.nb_NO.ts
    translation.lv_LV.ts
    [OMIT_SOURCE_LANGUAGE]
)

<MainProject>.qmlproject 中的 TranslationFiles 节点取代上述命令

TranslationFiles {
    files: [
        "translation.nb_NO.ts",
        "translation.lv_LV.ts"
    ]
    MCU.omitSourceLanguage: true|false
}

最大资源缓存大小

废弃的CMake命令QmlProject替换(MCU.Config节点)描述
qul_set_maximum_resource_cache_sizemaxResourceCacheSize (属性)设置给定运行时资源分配类型的最大资源缓存大小。

所有使用较旧版本的Qt for MCUs的项目,通过使用 qul_set_maximum_resource_cache_size() CMake API来为不同的分配类型定义资源缓存大小。自Qt for MCUs 2.4以来,此CMake API已废弃。将其对应的QmlProject中的节点替换掉,这个节点是 MCU.Config 节点中的 maxResourceCacheSize 属性。

以下示例展示了如何在项目的 CMakeLists.txt 中使用 qul_set_maximum_resource_cache_size()

# DEPRECATED
qul_set_maximum_resource_cache_size(
    <target>
    CACHE_SIZE 512
)
qul_set_maximum_resource_cache_size(
    <target>
    CACHE_SIZE 1024
    RUNTIME_ALLOCATION_TYPE 1
)
qul_set_maximum_resource_cache_size(
    <target>
    CACHE_SIZE 2048
    RUNTIME_ALLOCATION_TYPE 128
)

<MainProject>.qmlproject 文件中的 maxResourceCacheSize 属性取代上述代码片段,如下所示

MCU.Config {
    maxResourceCacheSize: [
        [512],      // 512 bytes cache for resources using the default runtime allocation type
        [1024, 1],  // 1024 bytes cache for resources using runtime allocation type 1
        [2048, 128] // 2048 bytes cache for resources using runtime allocation type 128
    ]
}

目标和应用程序变体

有时需要为不同的目标平台上的同一应用使用不同的源文件或不同的属性配置,或者配置应用程序变体。本节描述如何在2.4及以上版本的Qt for MCUs中完成此操作。

文件变体

文件选择器的概念提供了在为特定目标构建项目时区分哪个源文件或资源变体的简单方法。使用文件选择器时,请将文件变体放在正确的目录中。有关如何正确使用选择器的更详细说明,请参阅 fileSelector的文档。在CMake中添加目标时,在 qul_add_target() 中使用 SELECTORS 参数来为特定目标选择文件变体。

# This target uses the default variant of all files
qul_add_target(<target>
    QML_PROJECT <MainProject>.qmlproject
)

# This target uses the "big" variant of all files where the variant is available
qul_add_target(<target_big>
    QML_PROJECT <MainProject>.qmlproject
    SELECTORS big
)

也可以只在某些 .qmlproject 文件或QmlProject文件的特定节点中使用文件选择器,并使用 fileSelector 属性。以下示例展示了为所有可用节点使用 small 文件选择器,并只为 MainScreen.qml 源文件使用 landscape 选择器。

import QmlProject 1.3
Project {
    MCU.Config {
        fileSelector: ["small"]
    }

    QmlFiles {
        files: ["MainScreen.qml"]
        fileSelector: ["landscape"]
    }

    ImageFiles {
        files: ["img.png"]
    }
}

每个目标都有一个QmlProject文件

如果每个目标对特定资源(如图像或字体)的处理方式不同,那么这种设置的配置通常可以在 MCU.Config 节点或 .qmlproject 文件中的 ImageFiles 节点找到。在这种情况下,可能需要为不同的配置创建不同的 .qmlproject 文件。例如,为两个不同的目标平台创建一个项目,其中一个平台闪存内存不足,需要压缩某些图像资源。在这种情况下,创建两个单独的 qmlproject 文件。

<MainProject>.qmlproject:

ImageFiles {
    files: ["img.png"]
}

<MainProject>_smallflash.qmlproject:

ImageFiles {
    files: ["img.png"]
    MCU.resourceCompression: true
}

在这种情况下,需要在 CMake 中向目标传递正确的 QmlProject,如下面的代码片段所示

# Adding target with limited flash memory
qul_add_target(
    <target_smallflash>
    QML_PROJECT <MainProject>_smallflash.qmlproject
)

# Adding target with more flash memory
qul_add_target(
    <target>
    QML_PROJECT <MainProject>.qmlproject
)

自定义平台端口

自定义平台端口的流程与 Qt for MCUs 2.3 相同。有关如何将自定义平台端口迁移到 Qt for MCUs 2.4 及更高版本的说明,请参阅 平台迁移指南

迁移平台端口

一个 .qmlprojectconfig 文件应该包含平台的默认设置。此文件与 .qmlproject 文件具有相同的语法,并且 qmlprojectexporter 使用它作为平台级默认值的源。

自 Qt for MCUs 2.3 以来,平台端口应已包含此文件。有关将旧平台迁移到 Qt for MCUs 2.3 及更高版本的详细说明,请参阅 迁移到 Qt for MCUs 2.3 的平台迁移指南

在 CMake 中使用 QmlProject

自 Qt for MCUs 2.4 以来,qmlprojectexporter 工具解析项目中的 .qmlproject 文件(夹),并运行相关工具为目标平台生成代码。 qmlprojectexporter 将所有生成的文件放置在预定的输出目录中。这使得将 Qt for MCUs 集成到所选择的构建系统中变得更容易。有关 qmlprojectexporter 的详细信息及其手动使用说明,请参阅 qmlprojectexporter 文档。以下部分演示了如何从 CMake 使用此工具。

与 Qt for MCUs 的早期版本相比,CMake API 的更改是显著的。所有资源、源文件和属性配置现在都位于一个 .qmlproject 文件中。现有的 qul_add_target() 自定义 CMake 命令接受一个 .qmlproject 文件作为参数。此参数提示 CMake 运行 qmlprojectexporter并为项目生成源文件,并为这些文件创建构建目标。以下代码片段演示了如何使用 CMake 和 .qmlproject 文件构建 Qt for MCUs 项目。

cmake_minimum_required(VERSION 3.21.1)

project(<project_title> VERSION 0.0.1 LANGUAGES C CXX ASM)

find_package(Qul)

# This is where qmlprojectexporter is invoked
qul_add_target(<target>
    QML_PROJECT <MainProject>.qmlproject
    [GENERATE_ENTRYPOINT]
)

app_target_setup_os(<target>)

注意: 当在 qul_add_target() 中使用 GENERATE_ENTRYPOINT 选项以提示入口点生成时,.qmlproject 文件必须定义具有 mainFile 属性的入口点 QML 文件。有关详细信息,请参阅 qul_add_target

项目迁移示例

以下示例演示了如何将现有 CMake 项目迁移到 Qt for MCUs 2.4 及更高版本的 QmlProject 格式。此示例仅演示了示例 CMakeLists.txt.qmlproject 文件的内容。

已迁移的项目仍然使用CMake构建,但没有废弃的API,所以CMakeLists.txt更加简单。项目包含两个新的.qmlproject文件:一个用于模块,另一个用于主项目。

CMake项目

这个示例项目使用了废弃的CMake API,因此下一节演示了如何进行迁移。下面是原始项目的CMakeLists.txt

CMakeFiles.txt

cmake_minimum_required(VERSION 3.21.1.)

project(<project> VERSION 1.0 LANGUAGES C CXX ASM)

find_package(Qul)

qul_add_target(<target>)

# DEPRECATED
# Add QML sources
qul_target_qml_sources(<target> MainScreen.qml Menu.qml)

# DEPRECATED
# Generate QML interfaces to C++ code
qul_target_generate_interfaces(<target> test_model.h QML_IMPORTS QtQuick)

# DEPRECATED
# Add QML module
qul_add_qml_module(
    <target>
    URI MyModule
    QML_FILES CustomComponent.qml
)

# DEPRECATED
# Add translation files (keep source language)
qul_target_embed_translations(<target> translation.fr_FR.ts translation.de_DE.ts)

# DEPRECATED
# Set default setting for resource compression
set(QUL_DEFAULT_RESOURCE_COMPRESSION ON)

# DEPRECATED
# Set resource file properties
set_source_files_properties(
    progress_spinner.png
    PROPERTIES
        QUL_OPTIMIZE_FOR_ROTATION ON
)
set_source_files_properties(
    background_city.png
    background_forest.png
    PROPERTIES
        QUL_RESOURCE_CACHE_POLICY "OnDemand"
        QUL_RESOURCE_STORAGE_SECTION "CustomSegment"
        QUL_RESOURCE_RUNTIME_ALLOCATION_TYPE "128"
        QUL_RESOURCE_COMPRESSION OFF
)

# DEPRECATED
# Add image resources
qul_add_resource(
    <target> FILES
        progress_spinner.png
        background.png
        background_city.png
        background_forest.png
)

# DEPRECATED
# Add fonts
set_target_properties(
    <target>
    PROPERTIES
        QUL_FONT_ENGINE "Spark"
        QUL_FONT_FILES "font.ttf"
        QUL_DEFAULT_FONT_FAMILY "default"
        QUL_MAX_PARAGRAPH_SIZE 80
)

# DEPRECATED
# Define resource cache sizes
qul_set_maximum_resource_cache_size(
    <target>,
    32800
)
qul_set_maximum_resource_cache_size(
    <target>,
    15600,
    RUNTIME_ALLOCATION_TYPE 1
)
qul_set_maximum_resource_cache_size(
    <target>,
    512900,
    RUNTIME_ALLOCATION_TYPE 128
)

# Link the Qul::Controls library
target_link_libraries(<target> PRIVATE Qul::Controls)

# Setup os (baremetal or freertos)
app_target_setup_os(<target>)

# Generate default entrypoint from QML source
app_target_default_entrypoint(<target> MainScreen)

已迁移项目

自从Qt for MCUs 2.4版本以来,该项目需要两个.qmlproject文件,一个用于模块,另一个用于主项目。

在使用CMake构建时,qul_add_target命令将主项目的.qmlproject文件作为QML_PROJECT参数,提示qmlprojectexporter生成所需文件。

CMakeLists.txt:

cmake_minimum_required(VERSION 3.21.1.)

project(<project> VERSION 1.0 LANGUAGES C CXX ASM)

find_package(Qul)

# Add the target using a QmlProject file
# Generate a custom entrypoint based on the mainFile property with GENERATE_ENTRYPOINT
qul_add_target(<target> QML_PROJECT MainProject.qmlproject GENERATE_ENTRYPOINT)

app_target_setup_os(<target>)

MainProject.qmlproject:

import QmlProject 1.3

Project {

    mainFile: "MainScreen.qml"

    QmlFiles {
        files: ["Menu.qml"]
    }

    InterfaceFiles {
        files: ["test_model.h"]
        MCU.qmlImports: ["QtQuick"]
    }

    ModuleFiles {
        files: ["MyModule.qmlproject]
        MCU.qulModules: [
            "Qul::Controls"
        ]
    }

    // Image resources are added in ImageFiles nodes.
    // Use one node per unique configuration of properties
    ImageFiles {
        files: [
            "background_city.png",
            "background_forest.png"
        ]
        MCU.resourceCachePolicy: "OnDemand"
        MCU.resourceStorageSection: "CustomSegment"
        MCU.resourceRuntimeAllocationType: 128
        MCU.resourceCompression: false
    }

    ImageFiles {
        files: ["progress_spinner.png"]
        MCU.resourceOptimizeForRotation: true
    }

    ImageFiles {
        files: ["background.png"]
    }

    FontFiles {
        files: ["font.ttf"]
    }

    TranslationFiles {
        files: [
            "translation.fr_FR.ts",
            "translation.de_DE.ts"
        ]
    }

    MCU.Config {
        // Font properties
        fontEngine: "Spark"
        defaultFontFamily: "default"
        maxParagraphSize: 80

        // Image properties
        resourceCompression: true

        // Storage
        maxResourceCacheSize: [
            [32800],
            [15600, 1],
            [512900, 128]
        ]

    }
}

MyModule.qmlproject

import QmlProject 1.3

Project {
    MCU.Module {
        uri: "MyModule"
    }

    QmlFiles {
        files: ["CustomComponent.qml"]
    }
}

另请参阅QmlProject 手册.

在一定的Qt许可证下可用。
了解更多。