はじめに

qmlprojectexporter は、プロジェクトに含まれるすべてのリソースおよび .qml ファイルに対して、C++ コードを自動生成できるツールです。リソースには、Qml ファイル、画像、フォントファイル、翻訳ファイル、および C++ インターフェースが含まれます。qmlprojectexporter の主な引数として、.qmlproject ファイルを指定する必要があります。このファイルはプロジェクトの構造を定義しており、他の .qmlproject モジュールファイルに依存している場合があります。

qmlproject ファイル

.qmlproject ファイルの構文は、QML ドキュメントと同じ構文を使用します。.qmlproject ファイルの目的は、プロジェクトの構造を記述することです。 QMLドキュメントと同様に、.qmlprojectファイルは、インポートセクションと、それに続くノードまたはオブジェクトの階層構造で構成されています。階層はルートノード（この場合はProject）から始まり、各ノードにはあらかじめ定義されたプロパティのセットがあります。 インポートセクションは主に「import QmlProject 1.3」で構成されており、これが .qmlproject ファイルであることを示し、使用する API のバージョンを指定します。

移行ガイド

非推奨となった CMake API に依存している既存のプロジェクトを、.qmlproject を使用するように移行することができます。詳細については、『QmlProject への移行ガイド』を参照してください。

プラットフォームソースを含むプロジェクトのエクスポート

qmlprojectexporter コマンドラインユーティリティを使用すると、QmlProject をプラットフォームソースとともにエクスポートできます。これにより、Qt for MCUs をサードパーティ製のIDEやカスタムビルドシステムに統合するプロセスが簡素化されます。この機能の使用方法の詳細については、「プラットフォームソースを含むQt for MCUs プロジェクトのエクスポート」を参照してください。

ノード

各ノードは、プロジェクトの特定の部分（Qmlファイル、画像、モジュールなど）を構成します。ImageFilesなど、プロジェクトのルートノード内で複数回定義できるノードもあります。一方、MCU.Moduleなど、1回しか定義できないノードもあります。

プロパティ

.qmlproject ファイル内のプロパティは、設定パラメータと見なすことができます。各ノードには、設定可能な値の事前定義されたセットがあります。

プロジェクトファイル内で設定をサポートするすべてのノードに対し、MCU.Configノード内に配置することで設定を割り当てることができます。また、MCU.Config で定義された値は、対応するプロパティがデフォルトのノード（ImageFilesなど）に見つからない場合に有効になります。 これらの設定プロパティには「MCU.」というプレフィックスが付いています。詳細については、MCU.Configを参照してください。

ノード

プロジェクト

各qmlproject ファイルには、Project ノードがルートノードとして存在します。このルートノードには、プロジェクトに関する詳細情報を提供する他のすべてのノードが含まれています。

qmlproject ファイルの階層構造は、Project とその子ノードの2階層までとなっています。qmprojectexporter は、3階層目に配置されたノードを無視します。

使用方法

Project {
    projectRootPath: "..."
    ...
    MCU.Config {...}
    ...
    ImageFiles {...}
    ...
}

以下は、Project ノードで使用可能なプロパティの一覧です：

QmlFiles

このノードを使用すると、プロジェクトのQMLファイルを一覧表示できます。QMLファイルへのパスには、相対パスと絶対パスの両方を指定可能です。

使用方法

QmlFiles {
    files: ["src/other.qml"]
}

以下は、QmlFilesノードで使用可能なプロパティの一覧です：

ImageFiles

ImageFiles ノードは、指定された画像アセットをプロジェクトに追加します。

さらに、指定されたノードで指定されたプロパティは、qulrcc-toolがこれらのアセットをエンコードする方法に影響を与えます。

同じプロジェクト内に複数の ImageFiles を配置することが可能です。これは、画像のグループごとに異なるプロパティを設定する際に必要となります。

ImageFiles ノードで特定のプロパティを定義していない場合、qmlprojectexporter はMCU.Configノードで指定されたデフォルト値を使用します。そこに定義されていない場合は、グローバルなデフォルト値が適用されます。

使用方法

Project {
    ...
    ImageFiles {
        files: [...]
        MCU.resourceOptimizeForRotation: true
    }
    ...
}

以下は、ImageFilesノードで使用可能なプロパティの一覧です：

FontFiles

このノードを使用すると、プロジェクトで必要なフォントファイルを一覧表示できます。サポートされているフォントファイル形式については、フォント形式を参照してください。

使用方法

Project {
    ...
    FontFiles {
        files: [...]
    }
    ...
}

以下は、FontFiles ノードで使用可能なプロパティの一覧です：

TranslationFiles

このノードを使用すると、プロジェクトに翻訳ファイルを追加できます (.ts)。

qmlprojectexporter は、これらの翻訳ファイルを.qm ファイルに変換するために、対応するツールを呼び出します。 ファイルは、Qt が翻訳を管理するために使用するバイナリ形式です。

QMLソースでは、qsTr() またはqsTrId() を使用して、翻訳可能な文字列を指定できます。実行時、翻訳システムは現在のシステムロケールに対応する翻訳ファイル内で、一致する文字列を検索します。

使用方法

Project {
    ...
    TranslationFiles {
        files: [...]
    }
    ...
}

TranslationFiles ノードでは、以下のプロパティがサポートされています:

InterfaceFiles

このノードは、C++インターフェース固有の設定を提供します。QMLファイルにインポートすることなく、C++インターフェースを定義し、QMLから参照できるようにすることが可能です。qmlprojectexporterは、これらのC++インターフェースのヘッダーファイルに基づいてQMLコードを生成するため、同じプロジェクト内の別のQMLファイルからそれらを参照できるようになります。

使用方法

Project {
    ...
    InterfaceFiles {
        files: [...]
    }
    ...
}

以下は、InterfaceFilesノードで使用可能なプロパティの一覧です：

バイナリファイル

BinaryFiles ノードは、指定されたバイナリアセットをプロジェクトに追加します。

さらに、指定されたノードで指定されたプロパティは、qulrcc-toolがこれらのアセットをどのように処理するかに影響します。

同じプロジェクト内に複数の「BinaryFiles」ノードを配置することが可能です。これは、バイナリアセットのグループごとに異なるプロパティを設定する際に必要となります。

BinaryFiles ノードで特定のプロパティを定義していない場合、qmlprojectexporter はMCU.Configノードで指定されたデフォルト値を使用します。そこに定義されていない場合は、グローバルなデフォルト値が使用されます。

使用方法

Project {
    ...
    BinaryFiles {
        files: [...]
    }
    ...
}

以下は、BinaryFilesノードで使用可能なプロパティの一覧です：

MCU.Config

このノードを使用すると、QmlProjectファイルのデフォルト値を定義できます。このノードのコンテキスト内で定義されるプロパティには、"MCU." というプレフィックスを付ける必要はありません。一方、ImageFilesやFontFilesなどの特定のノードの一部として同じプロパティを定義する場合は、このプレフィックスを使用する必要があります。

使用方法

//node1
MCU.Config {
  // Project-wide default value for resourceOptimizeForRotation.
  resourceOptimizeForRotation: true
}

ImageFiles {
  // Here resourceOptimizeForRotation was explicitly defined for a specific ImageFiles node.
  MCU.resourceOptimizeForRotation: false // requires the "MCU."prefix
}

//node2
ImageFiles {
  // MCU.resourceOptimizeForRotation was not defined but the value \c true will be
  // picked from MCU.Config.
}

以下は、MCU.Config で利用可能なプロパティの一覧です:

ResourceStorageSection

このノードを使用して、リソースストレージセクションのプロパティを指定できます。アプリケーションで使用される各リソースストレージセクションに対して、複数のノードを指定できます。

これらのノードは、MCU.Config ノードの子ノードである必要があります。

使用方法

MCU.Config {
        ResourceStorageSection
        {
            name: "ResourceDataInInternalFlash"
            majorVersion: 2
            minorVersion: 1
        }

        ResourceStorageSection
        {
            name: "ResourceDataInExternalFlash"
            majorVersion: 1
            minorVersion: 0
        }
}

以下は、ResourceStorageSection で利用可能なプロパティの一覧です：

MCU.Module

このノードの役割は、qmlprojectファイルをモジュールとして宣言することです。モジュールには、アセット、インターフェース、QMLコンポーネント、および翻訳を含めることができます。qmlprojectベースのプロジェクトでは、QmlProjectのModuleFilesノードを使用して、qmlprojectベースのモジュールを活用することができます。

使用方法

// mymodule.qmlproject
import QmlProject 1.3
Project {
  MCU.Module {
    uri: "custom.module"
  }
  QmlFiles {
    files: ["CustomBox.qml"]
  }
}

// CustomBox.qml
// ... some qml code

// main.qmlproject
import QmlProject 1.3
Project {
  QmlFiles {
    files: ["main.qml"]
  }
  ModuleFiles {
    files: ["mymodule.qmlproject"]
  }

// main.qml
import QtQuick 2.15
import custom.module
Rectangle {
  CustomBox {}
}

Qul モジュール

Qt Quick Ultralite には、プロジェクトでModuleFiles.MCU.qulModules を使用して利用できる、以下の事前定義済みモジュールが付属しています：

• Controls
• ControlsTemplates
• レイアウト
• Location
• プロファイリング
• 配置
• SafeRenderer
• 形状
• StudioComponents
• Timeline
• VirtualKeyboard

以下は、MCU.Module ノードで使用可能なプロパティの一覧です:

ModuleFiles

このノードを使用して、QMLモジュールをプロジェクトにインポートできます。

使用方法

Project {
    ...
    ModuleFiles {
        MCU.qulModules: [...]
        ...
    }
    ...
}

以下は、ModuleFilesノードで使用可能なプロパティの一覧です：

コマンドラインリファレンス

qmlprojectexporter

qmlprojectexporterを使用すると、QML ソース、画像アセット、およびフォントをコンパイル可能な C++ コードとしてエクスポートできます。このツールは、エクスポートオプションとともにアセットを列挙した `.qmlproject ` ファイルを解析します。 さらに、qmlprojectexporter は、インポートおよびエクスポートされたファイルのプレーンテキストリストもエクスポートするため、CMake などのサードパーティ製ビルドシステムで自動的に利用しやすくなっています。

CMakeプロジェクトにおけるqmlprojectexporter の使用方法

CMakeビルドシステムでのqmlprojectexporter の使用方法は簡単で、カスタムCMakeマクロqul_add_targetが、適切なパラメータを指定してqmlprojectexporter を呼び出す処理をすでに担当しています。これを使用するには、次のようにQML_PROJECT引数を定義し、その後にqmlprojectファイルを指定する必要があります。

// Adding the \l GENERATE_ENTRYPOINT option will generate an application entrypoint automatically,
// but it requires setting the \l Project.mainFile property
qul_add_target(my_project QML_PROJECT my_project.qmlproject GENERATE_ENTRYPOINT)

// Note for a working Qul application with CMake it is still required to call \l app_target_setup_os macro
// after adding the qmlproject target.
app_target_setup_os(myproject)

qmlprojectexporter を使用する場合、qmlprojectexporter の呼び出しによって同じ機能が実行されるため、以下の CMake マクロは必要ありません。

• qul_target_qml_sources
• qul_target_generate_interfaces
• qul_target_embed_translations
• qul_add_qml_module

QmlProject の代替機能によって置き換えられたすべての CMake フラグは、CMake マニュアルにおいて非推奨としてマークされています。

スタンドアロンでの使用qmlprojectexporter

CMake以外のビルドシステムを使用する場合でも、qmlprojectexporter を直接使用することは可能です。生成されたアセットファイルは、任意のビルドシステムで使用できます。

qmlprojectexporter --outdir output_directory myproject.qmlproject

以下に、qmlprojectexporter のコマンドライン引数の詳細な一覧を示します：

qmlprojectexporterによって生成されたファイル

出力ディレクトリに生成されるファイルは、使用するコマンドライン引数によって異なります。プロジェクトのビルドプロセスにおいてqmlprojectexporter がどのような役割を果たしているかをより深く理解するには、Qt Quick を参照してください。Ultraliteツール以下のリストは、次の例に基づいて生成される可能性のあるファイルの一覧です：

以下のスタートアッププロジェクトファイルを例に考えてみましょう：

エクスポートなし

qmlprojectexporter --no-export-cpp --no-export-modules --no-export-configuration --outdir output my_project.qmlproject

このコマンドを実行すると、output ディレクトリが作成されますが、このコマンドはすべてのエクスポートを無効にするため、その中にファイルは作成されません。

エクスポート設定

qmlprojectexporter --no-export-cpp --no-export-modules --outdir output my_project.qmlproject

--no-export-configuration引数を削除すると、以下のファイルが生成されます：

前述のコマンドを使用すると、ファイルを生成するオーバーヘッドを伴わずに、プロジェクトで必要とされるリソースや構成に関する情報を取得することができます。

CPPファイルのエクスポート

qmlprojectexporter --no-export-modules --outdir output my_project.qmlproject

--no-export-configuration を削除すると構成一覧が表示されますが、--no-export-cpp を削除すると、プロジェクト用の実際のCPP ファイルがすべて生成されます。Qt Quick Ultralite toolsでは、どのツールがどのファイルを担当しているかについて解説しています。

モジュールのエクスポート

qmlprojectexporter --outdir output my_project.qmlproject

先の例で、--no-export-modulesオプションを指定せずにqmlprojectexporter を実行しても、その例ではモジュールファイルが一切使用されていないため、出力フォルダに大きな変化はありません。しかし、プロジェクトをモジュールごと完全にエクスポートすると、サードパーティ製ツールが使用する出力ディレクトリに 2 つのファイルが表示されます。それらのファイルは以下の通りです：

--no-export-modules の主効果を確認するには、以下の新しいプロジェクトファイルを参照してください：

新しいファイルを使用して前述の `qmlprojectexporter ` コマンドを実行すると、以下の結果になります：

qmlprojectexporter --no-export-modules を省略し、--no-export-cpp を使用すると、構成 txt ファイルが生成されます。

デフォルトのアプリケーションエントリポイントを持つモジュールのエクスポート

既存のエントリポイントがある場合、次のステップで生成されるファイルは必要ありません。以下のコマンドについて考えてみましょう。

//[1]
qmlprojectexporter --generate-entrypoint --target-type executable --outdir output my_project.qmlproject
//[2]
qmlprojectexporter --generate-entrypoint --target-type static_library --outdir output my_project.qmlproject

qmlprojectexporter --target-type フラグの設定に応じて、生成されるファイルのリストに新しいファイルが追加されます。

実行ファイルを使用する場合：

static_library を使用する場合:

qulpreview (テクノロジープレビュー)

qulpreview QMLプロジェクトをターゲットプラットフォームに迅速かつ簡単にデプロイするために使用できます。最も基本的なシナリオでは、このツールは次のように使用できます：

qulpreview <QMLPROJECT>

ここで、<QMLPROJECT> はプロジェクトの.qmlproject ファイルへのパスです。動作は、--profile <PROFILE_ID> および--workflow <WORKFLOW_ID> というコマンドライン引数を使用してさらにカスタマイズできます。ここで、<PROFILE_ID> と<WORKFLOW_ID> は、それぞれターゲットプロファイルの ID と、デプロイ手順を記述するワークフローの ID です。

現在のテクノロジープレビュー段階では、Qt for MCUs には2つのプロファイルのみが同梱されており、いずれもデスクトップ向けQt XMLを対象としています。Windows用がwin-mingw 、Linux用がlinux-gcc です。

利用可能なプロファイルの一覧は、qulpreview --list-profiles を実行することで取得できます。

プロファイルでは、繰り返しパターンを最小限に抑えるために変数を利用できます。構文は${VAR_NAME} です。

環境変数も利用可能で、env: というプレフィックスを使用して参照できます（例：${env:PATH} ）。

プロファイル作成者の利便性を考慮し、このツールでは、主にプロジェクトに関連するいくつかの事前定義済み変数が用意されています：

• OUT_DIR - 推奨出力先。qulpreview 自体はアーティファクトを生成しませんが、この変数をレシピ内で使用することで、ツールの出力をカスタマイズできます。--out-dir のコマンドライン引数で指定可能です
• PROJECT_FILE_PATH -.qmlproject ファイルへのフルパス（プロジェクトファイル自体を含む）
• PROJECT_FILE_NAME - プロジェクトファイル名（拡張子を含む）
• PROJECT_BASE_NAME - プロジェクトファイル名（拡張子を除く）
• PROJECT_DIR - プロジェクトファイルの親ディレクトリ

レシピ内のステップは順次実行され、あるステップが失敗した場合（開始できない、クラッシュする、ゼロ以外の終了コードで終了するなど）、その後のステップは実行されません。

qulpreview でエラーが発生した場合、EXIT_FAILURE のエラーコードで終了し、エラーはstderr に出力されます。

以下に、qulpreview コマンドライン引数の詳細な一覧を示します。