qt_add_protobuf

Protobufスキーマを使用して、QtベースのC++ソースコードを生成します。

このコマンドは、Qt6 パッケージの Protobuf コンポーネントで定義されています。以下のコマンドでパッケージを読み込みます:

find_package(Qt6 REQUIRED COMPONENTS Protobuf)

このコマンドは Qt 6.5 で導入されました。

qt_add_protobuf を使用して、CMake スクリプト内で `qtprotobufgen ` を呼び出し、プロジェクトの .proto スキーマからコードを生成します。`qtprotobufgen ` は、CMake を通じて `qt_add_protobuf ` コマンドを使用して呼び出されます。

概要

qt_add_protobuf(<target>
    PROTO_FILES <file> ...
    [PROTO_INCLUDES <path> ...]
    [QML [QML_URI <uri>]]
    [OUTPUT_DIRECTORY <dir>]
    [GENERATE_PACKAGE_SUBFOLDERS]
    [COPY_COMMENTS]
    [EXPORT_MACRO <infix>]
    [OUTPUT_HEADERS <var>]
    [OUTPUT_TARGETS <var>]
    [HEADER_GUARD <pragma|filename>]
    [GENERATE_NON_FINAL_MESSAGES] # since Qt 6.11
    [GENERATE_NON_FINAL_PROPERTIES] # since Qt 6.12
)

バージョン指定なしのコマンドが無効になっている場合は、代わりに `qt6_add_protobuf() ` を使用してください。このコマンドと同じ引数セットをサポートしています。

説明

qtprotobufgen によって生成されたソースファイルは、ターゲットに追加されます。ターゲットがすでに存在する場合、生成されたファイルはターゲットのソースリストに追加されます。ターゲットが存在しない場合は、リンクが必要なライブラリとして作成されます。

• PROTO_FILES コード生成手順で使用される.protoファイルのリストを指定します。
• PROTO_INCLUDES protobufの依存関係を検索するディレクトリのリストを指定します。

  注： PROTO_FILES の場所は 、暗黙的に protobuf のインクルードパスの一部とみなされます。

• QML protobuf 定義から QML 互換のメッセージ型を生成し、それらを QML モジュールとして登録します。qt_add_protobuf が、存在しないターゲット、または QML モジュールではないターゲットに対して呼び出された場合、新しい QML モジュールが暗黙的に作成されます。

  find_package(Qt6 6.8 REQUIRED COMPONENTS Quick Protobuf ProtobufQuick)
  ...
  qt_add_executable(target
      ...
  )
  // creates a new QML module
  qt_add_protobuf(target
      QML
      ...
  )

  targetが既存のQMLモジュールである場合、qt_add_protobuf は生成されたprotobuf型をそのモジュールに追加します。

  find_package(Qt6 6.8 REQUIRED COMPONENTS Quick Protobuf ProtobufQuick)
  ...
  qt_add_qml_module(target
      ...
  )
  // adds to existing QML module
  qt_add_protobuf(target
      QML
      ...
  )

  注: QML引数を使用する場合は 、find_packageの呼び出しにProtobufQuickを追加する必要があります。上記の例を参照してください。

• QML_URI QMLモジュールで使用されるURI を定義します。

  すべてのQMLモジュールは、URI を定義する必要があります。これは、import文で使用され、そのprotobuf型をQMLに公開するために使用されます。

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

  QML_URI が省略された場合、protobufのパッケージ名がモジュールのURI として使用されます。

  注： QML_URI が省略された場合 、PROTO_FILES セクションで指定されたすべての.protoファイルは、生成されるQMLモジュールのデフォルトのURI として使用されるため、同じprotobufパッケージ名を共有する必要があります。

  注： QML_URI やprotoパッケージ名が同じ複数のprotobuf QMLモジュールを作成することは避けてください 。QMLコンテキストでインポートエラーが発生する原因となります。

  注： QML_URI がqt_add_protobuf 関数に渡されたものの、ターゲットがすでに存在する場合 、QML_URI 引数は無視されます。

  URI に関するより詳細な説明については、「識別されたモジュール」を参照してください。

• OUTPUT_DIRECTORY 生成されたファイルが配置されるディレクトリを指定します。デフォルトでは、現在のビルドディレクトリが使用されます。
• GENERATE_PACKAGE_SUBFOLDERS .proto ファイルのパッケージ名指定子を使用して、生成されたファイルのフォルダ構造を作成します。たとえば、パッケージが と定義されている場合、生成されたファイルはpackage io.qt.testOUTPUT_DIRECTORY/io/qt/test/ に配置されます。
• COPY_COMMENTS .proto ファイル内のコメントを生成されたコードにコピーします。
• EXPORT_MACRO <target> から新しい共有ライブラリを作成する場合にのみ適用されます。このオプションは、生成されたコードで使用されるエクスポートマクロのベース名を指定します。最終的なマクロ名はQPB_<EXPORT_MACRO>_EXPORT の形式で構成されます。このオプションが設定されていない場合、ターゲット名がEXPORT_MACRO として使用されます。

  詳細については、「共有ライブラリの作成」を参照してください。

• OUTPUT_HEADERS 生成されたヘッダーのリストを格納する変数を指定します。このリストは、カスタムプロジェクトのインストールルールを定義する際に役立ちます。
• OUTPUT_TARGETS 生成されたターゲットのリストを格納する変数を指定します。このリストは、カスタムプロジェクトのインストールルールを定義する際に役立ちます。
• HEADER_GUARD 生成されたヘッダーファイルが複数回インクルードされるのを防ぐために使用されるメカニズムを指定します。指定可能な値は、pragma 、filename です。デフォルトはfilename です。このオプションをpragma に設定すると、最新の pragma ヘッダーガードが生成されます:

  #pragma once
  ...

  このオプションを省略するか、filename に設定すると、ifdef によるラップ型ガードが生成され、ファイル名 '.proto' がガードの接頭辞として使用されます:

  #ifdef MYMESSAGES_QPB_H
  #define MYMESSAGES_QPB_H
  ...
  #endif // MYMESSAGES_QPB_H

  プロジェクトの構造に応じて、適切なガードスタイルを選択してください。

• GENERATE_NON_FINAL_MESSAGES (Qt 6.11 以降) では、final 指定子なしのQtProtobuf メッセージクラスが生成されます。このオプションは下位互換性のために提供されています。Qt 6.11 以降、QtProtobuf メッセージクラスはデフォルトでfinal として生成されます。生成されたメッセージの挙動を拡張するには、継承よりもコンポジションを優先してください。このオプションは Qt 7 で削除される予定です。
• GENERATE_NON_FINAL_PROPERTIES (Qt XML 6.12以降)FINAL 指定子なしで、QtProtobuf メッセージクラスのプロパティを生成します。FINAL 指定子を使用すると、QMLツールがパフォーマンスの最適化を適用し、より効率的なコードを生成できるようになります。Qt 6.12以降、QtProtobuf メッセージのプロパティは、デフォルトでFINAL 指定子付きで生成されます。このオプションは下位互換性のためだけに提供されており、Qt 7で削除される予定です。FINAL 指定子の詳細については、『Qt Property System』を参照してください。

protobuf ターゲット間の依存関係の解決

qt_add_protobuf コマンドは、異なるターゲット向けのコードを生成するために使用される.proto ファイル間の依存関係を考慮しません。

プロジェクトには、依存関係を持つ 2 つ以上の.proto ファイルが存在する場合があります:

// test_messages.proto
syntax = "proto3";

package test.messages;

message MyMessage {
    int32 myField = 1;
}

// test_extensions.proto
syntax = "proto3";

import "test_messages.proto";

package test.extensions;

message MyExtension {
    test.messages.MyMessage baseMessage = 1;
    int32 extension = 2;
}

上記の.proto ファイルは、スタンドアロンライブラリの生成に使用できます：

qt_add_protobuf(test_messages
    PROTO_FILES
        test_messages.proto
)
...
qt_add_protobuf(test_extensions
    PROTO_FILES
        test_extensions.proto
)
...

test_extensions ターゲットはtest_messages ターゲットからのメッセージに依存しているため、CMake スクリプト内でこれらのターゲットへのリンクを手動で指定する必要があります：

target_link_libraries(test_extensions PUBLIC test_messages)

例

qt_add_protobuf の使用

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Protobuf)
qt_standard_project_setup()

qt_add_protobuf(MyMessages
    GENERATE_PACKAGE_SUBFOLDERS
    PROTO_FILES
        path/to/message.proto
        path/to/other_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_executable(MyApp main.cpp)

target_link_libraries(MyApp PRIVATE MyMessages)

上記の例では、MyMessages というライブラリを生成します。このライブラリには、PROTO_FILES オプションに渡されたパスで定義されたメッセージ型が含まれます。GENERATE_PACKAGE_SUBFOLDERS オプションは、生成されたファイル用のフォルダ構造を生成します。また、PROTO_INCLUDES オプションは、protocに指定されたディレクトリ内で依存関係やインポートを検索するよう指示します。MyApp という実行ファイル用のターゲットを作成し、これをMyMessages ライブラリにリンクします。

QML拡張protobufの例

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Protobuf ProtobufQuick Quick)
qt_standard_project_setup()

qt_add_protobuf(MyMessagesPlugin
    QML
    QML_URI my.messages.module.uri
    PROTO_FILES
        path/to/message.proto
        path/to/other_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_protobuf(MyApp
    QML
    PROTO_FILES
        path/to/internal_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_qml_module(MyApp
    URI example.uri
    VERSION 1.0
    QML_FILES qml/main.qml
)

qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Quick)

上記のQML拡張例では、最初のqt_add_protobuf 呼び出しにより、MyMessagesPlugin というQMLモジュールを生成します。このモジュールには、PROTO_FILES オプションに渡されたパスで定義されたメッセージ型が含まれます。 ここでは、QML オプションを使用しています。これにより、QML コンテキストでのprotoメッセージ型の登録が可能になります。登録された型は、QML_URI で設定されたパスをインポートすることで、QML で利用可能になります。2回目のqt_add_protobuf 呼び出しにより、既存のMyApp QMLモジュールに自動生成されたコードが追加されます。このような場合、QML_URI は不要です。 最後に、MyApp という名前の実行ファイル用のターゲットを作成します。この実行ファイルには、グラフィカル部分用のQMLモジュールが含まれており、my.messages.module.uri のインポートを通じてMyMessagesPlugin をmain.qmlファイルに読み込みます。

スタンドアロン版Qt Protobuf ライブラリのインストール

qt_add_protobufコマンドは、その後のインストールに必要なアーティファクトのリストも生成します。これらのアーティファクトは、次のようにOUTPUT_HEADERS およびOUTPUT_TARGETS 引数を指定することで確認できます:

qt_add_protobuf(MyProtoLib
    PROTO_FILES
        mylib.proto
    OUTPUT_HEADERS
        public_headers
    OUTPUT_TARGETS
        generated_targets
)

このコマンドは、qt_add_protobuf コマンドによって生成されたヘッダーファイルとターゲットのリストを、それぞれpublic_headers およびgenerated_targets 変数に格納します。

標準の CMake `install ` コマンドを使用して、アーティファクトをインストールし、ライブラリ用の `config ` ファイルを生成します:

include(GNUInstallDirs)
set_target_properties(MyProtoLib PROPERTIES
    PUBLIC_HEADER
        "${public_headers}"
    INTERFACE_INCLUDE_DIRECTORIES
        "$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}>"
)
install(TARGETS ${generated_targets} EXPORT MyProtoLibTargets
    PUBLIC_HEADER
        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
)
install(EXPORT MyProtoLibTargets NAMESPACE MyProtoLib:: DESTINATION lib/cmake/MyProtoLib)

その後、生成されたMyProtoLibTargets 設定をパッケージの設定ファイルで使用します。パッケージ作成プロセスに関する詳細は、CMakeの公式ドキュメントを参照してください。

インストール後、ライブラリはスタンドアロンの CMake パッケージとして利用可能になります:

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE MyProtoLib::MyProtoLib Qt6::Protobuf)