qt_add_protobuf

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

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

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

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>]
)

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

引数

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

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

• QML はprotobuf定義からQML互換のメッセージタイプを生成し、QMLモジュールとして登録します。存在しないターゲットやQMLモジュールでないターゲットに対してqt_add_protobuf を呼び出すと、暗黙のうちに新しい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
      ...
  )

  ターゲットが既存の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文の中でQMLにprotobufの型を公開するために使用されます。

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

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

  注： QML_URI が省略された場合、PROTO_FILES で指定されたすべての.protoファイルは同じ protobuf パッケージ名でなければなりません。なぜなら、URI が QML モジュールのデフォルトとして使用されるからです。

  注意： QMLコンテキストのインポートエラーにつながるため、QML_URI や proto パッケージ名が同じ protobuf QML モジュールを複数作成することは避けるべきです。

  注意 :qt_add_protobuf 関数にQML_URI が渡され、そのターゲットが既に存在する場合、QML_URI の引数は無視されます。

  URI の詳細については、Identified Modules を参照してください。

• OUTPUT_DIRECTORY は、生成されたファイルが置かれるディレクトリを定義します。デフォルトでは、現在のビルド・ディレクトリが使用されます。
• GENERATE_PACKAGE_SUBFOLDERS は、.proto ファイルのパッケージ名指定子を使用して、生成されるファイルのフォルダー構造を作成します。たとえば、パッケージがpackage io.qt.testと定義されている場合、生成されたファイルはOUTPUT_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 once
  ...

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

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

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

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)

上の例では、PROTO_FILES オプションに渡されたパスで定義されたメッセージタイプを含むMyMessages というライブラリを生成しています。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 の呼び出しによって、PROTO_FILES オプションに渡されたパスで定義されたメッセージタイプを含むMyMessagesPlugin というQMLモジュールを生成しています。QML オプションを使い、QML コンテキストにプロトメッセージ タイプを登録できるようにします。登録された型は、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 変数に格納します。

標準の CMakeinstall コマンドを使用してアーティファクトをインストールし、ライブラリの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 config をパッケージ config ファイルで使用します。パッケージの作成プロセスについては、公式の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)