このページでは

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 プロジェクトを定義できます。また、qul_add_target()QML_PROJECT オプションを指定することで、CMakeと併用することも可能です。このカスタム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.defaultFontFamilytext要素のデフォルトのフォントファミリー。
QUL_DEFAULT_FONT_QUALITYMCU.Config.defaultFontQualityText 要素のデフォルトのフォント品質。
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.glyphsStorageSectionRAM への事前ラスタライズ済みグリフデータの保存に使用するリソース保存セクションを設定します。
QUL_MAX_PARAGRAPH_SIZEMCU.Config.maxParagraphSize最大段落サイズを設定します。
QUL_CONTROLS_STYLEMCU.Config.controlsStyleコントロールスタイルを上書きします。

画像に関する非推奨のソースファイルプロパティ

非推奨となったCMakeソースファイルのプロパティQmlProjectの代替説明
QUL_RESOURCE_CACHE_POLICYImageFiles.MCU.resourceCachePolicy画像キャッシュのポリシーを定義します。
QUL_RESOURCE_COMPRESSIONImageFiles.MCU.resourceCompression画像を圧縮形式で保存します。
QUL_RESOURCE_IMAGE_PIXEL_FORMATImageFiles.MCU.resourceImagePixelFormat画像に最適なピクセル形式を設定します。
QUL_RESOURCE_OPTIMIZE_FOR_ROTATIONImageFiles.MCU.resourceOptimizeForRotation実行時に画像を回転させるための最適化を有効にします。
QUL_RESOURCE_OPTIMIZE_FOR_SCALEImageFiles.MCU.resourceOptimizeForScale実行時に画像を拡大・縮小するための最適化を有効にします。
QUL_RESOURCE_RUNTIME_ALLOCATION_TYPEImageFiles.MCU.resourceRuntimeAllocationTypeアセットのランタイム割り当てタイプを定義します。
QUL_RESOURCE_STORAGE_SECTIONImageFiles.MCU.resourceStorageSectionアセットのストレージセクションを定義します。

非推奨の CMake コマンド

非推奨の CMake コマンドQmlProjectの代替説明
qul_add_qml_moduleModuleFiles(<MainProject>.qmlproject 内のノード)プロジェクトに QML モジュールを追加します。モジュールには、独自の `.qmlproject ` ファイルが必要です。
MCU.Module(<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 ソースファイルを追加します。

QmlFilesノードは、プロジェクトに QML ソースファイルを追加する役割を担います。このノードは、filesプロパティにソースファイルのリストを受け取ります。このノードは、qul_target_qml_sources()というカスタム CMake コマンドに代わるものです。Qt for MCUs 2.4 へ移行する際は、CMake プロジェクトファイルからこのコマンドへの参照を削除してください。

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

CMakeLists.txt 内のqul_target_qml_source へのすべての参照を、.qmlproject ファイル(<MainProject>.qmlproject )内の以下の記述に置き換えてください:

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 ノードに置き換えてください:

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 (プロパティ)MCU.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 内のこれらを、プロパティ設定のセットごとに 1 つずつ、計 2 つのImageFiles ノードに置き換えてください:

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_FILESファイル(プロパティ)フォントファイルのパス一覧。
非推奨の CMake ターゲットプロパティMCU.Config プロパティ説明
QUL_AUTO_GENERATE_GLYPHSautoGenerateGlyphs(プロパティ)このオプションは、静的フォントエンジンにおけるグリフの自動生成を制御します。
QUL_COMPLEX_TEXT_RENDERINGcomplexTextRendering(プロパティ)複雑な文字体系のレンダリングを有効にします。
QUL_CONTROLS_STYLEcontrolsStyle(プロパティ)Controlsのスタイルを上書きします。
QUL_DEFAULT_FONT_FAMILYdefaultFontFamily(プロパティ)Text要素のデフォルトのフォントファミリー。
QUL_DEFAULT_FONT_QUALITYdefaultFontQuality(プロパティ)Text 要素のデフォルトのフォント品質。
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(プロパティ)最大段落サイズを設定します。

FontFilesノードのfilesプロパティを使用して、プロジェクトにフォントファイルを追加できます。このノードは、QUL_FONT_FILESCMake ターゲットプロパティに代わるものです。MCU.Configノードを使用して、フォントエンジンの選択など、フォント固有の設定を追加できます。前述のリストにあるすべてのフォントプロパティは、対応する 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でこの設定を定義するには、2つの異なるノードを使用する必要があります:

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(<MainProject>.qmlproject 内のノード)プロジェクトに QML モジュールを追加します。モジュールには、独自の `.qmlproject ` ファイルが必要です。
MCU.Module(<Module>.qmlproject 内のノード)このノードは、.qmlproject ファイルをモジュールに属するものとして指定し、その URI を定義します。

Qt for MCUs 2.4 以降、モジュールには独自の.qmlproject ファイルが必要です。 このファイルは、メインプロジェクトの.qmlproject ファイルと同様に機能しますが、モジュールの URI を定義するMCU.Moduleノードを 1 つだけ含める必要があります。表に示すように、<MainProject>.qmlproject 内のModuleFiles ノードと、各カスタムモジュール用の個別の.qmlproject ファイルの組み合わせにより、非推奨となった CMake コマンドqul_add_qml_module() が置き換えられます。

メインプロジェクトへのモジュールの組み込み

ModuleFilesノードの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 ファイルにモジュールを追加できるようになりました。以下の例は、<MainProject>.qmlproject でのその方法を示しています:

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

カスタムモジュールの作成

モジュールの.qmlproject ファイルには、モジュールのURIを定義するMCU.Moduleノードが1つだけ含まれている必要があります。このノードを除けば、モジュールの.qmlproject ファイルは他の.qmlproject ファイルと同様に機能します。

以下のスニペットは、前のセクションで使用した<Module>.qmlproject ファイルの完全な内容です。これは、URIがMyModule であるモジュールを記述しており、このモジュールにはCustomComponent.qml という単一のQMLファイルが含まれています。

import QmlProject 1.3

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

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

Qt Quick Ultralite モジュール

ModuleFilesノードを使用すると、Qt for MCUs SDK に含まれるモジュールをプロジェクトに追加することもできます。この目的でModuleFiles ノードを使用する場合は、プロジェクトの CMakeLists.txt から対応するtarget_link_libraries() を削除してください。

ModuleFiles ノードにはMCU.qulModulesというプロパティがあり、プロジェクトに追加するモジュールを指定する文字列のリストを受け取ります。

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

注: カスタムモジュール以外にも、ModuleFiles ノードを使用してQt for MCUs モジュールをリンクすることができます 。同じModuleFiles ノード内で、カスタムモジュールとQt for MCUs モジュールの両方を追加することも可能です。

翻訳

非推奨のCMakeコマンドQmlProjectの代替説明
qul_target_embed_translationsTranslationFiles(ノード).ts ファイルからの翻訳を埋め込みます。

TranslationFilesノードは、非推奨となったカスタム CMake コマンドqul_target_embed_translations() に代わるものです。Qt for MCUs 2.4 以降へ移植する際は、このコマンドへの参照をすべて削除してください。

このノードは、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 は非推奨となっています。 この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
    ]
}

ターゲットおよびアプリケーションのバリアント

異なるターゲットプラットフォーム上で同じアプリケーションに対して異なるソースファイルやプロパティ設定を使用したり、アプリケーションのバリアントを設定したりする必要がある場合があります。このセクションでは、Qt for MCUs 2.4以降でこれを行う方法について説明します。

ファイルバリアント

ファイルセレクタの概念により、特定のターゲット向けにプロジェクトをビルドする際に、どのソースファイルやリソースのバリアントを使用するかを簡単に区別できます。ファイルセレクタを使用する場合は、ファイルバリアントを適切なディレクトリに配置してください。 セレクタの適切な使用方法に関する詳細については、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
)

また、fileSelectorプロパティを使用することで、特定の.qmlproject ファイル内、またはQmlProjectファイルの特定のノード内でのみファイルセレクタを使用することも可能です。以下のスニペットでは、利用可能なすべてのノードでsmall ファイルセレクタを使用し、MainScreen.qml ソースファイルに対してのみlandscape セレクタを使用しています。

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

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

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

ターゲットごとの QmlProject ファイル

各ターゲットが画像やフォントなどの特定のリソースを異なる方法で処理する場合、その設定は通常、.qmlproject ファイル内のMCU. ConfigノードまたはImageFilesノードに記載されています。この場合、構成ごとに異なる.qmlproject ファイルを用意する必要があるかもしれません。 たとえば、2つの異なるターゲットプラットフォームを対象とするプロジェクトで、そのうち1つだけがフラッシュメモリが不足しており、特定の画像アセットを圧縮する必要がある場合です。このような場合は、2つの別々の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 以降へ移行する方法については、『Platform Migration Guide』を参照してください。

プラットフォーム・ポートの移行

.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 ファイル内に格納されるようになりました。 既存のカスタム CMake コマンド `qul_add_target()` は、引数として `.qmlproject ` ファイルを受け付けます。この引数を指定すると、CMake は `qmlprojectexporter ` を実行してプロジェクトのソースファイルを生成し、それらのファイルに対するビルドターゲットを作成します。以下のスニペットは、.qmlproject ファイルを使用して CMake で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を参照してください。

プロジェクト移行の例

以下の例は、Qt for MCUs 2.4以降で既存のCMakeプロジェクトをQmlProject形式に移行する方法を示しています。この例では、CMakeLists.txt および.qmlproject ファイルのサンプル内容のみを示しています。

移行後のプロジェクトは依然として CMake でビルドされますが、非推奨の API を除外したことで、CMakeLists.txt ははるかにシンプルになります。このプロジェクトには、モジュール用とメインプロジェクト用の 2 つの新しい.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以降、このプロジェクトには2つの.qmlproject ファイルが必要となります。1つはモジュール用、もう1つはメインプロジェクト用です。

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ライセンスの下で利用可能です。
詳細はこちらをご覧ください。