qtprotobufgen ツール

qtprotobufgen ツールを使用すると、protobufスキーマからQt Protobuf クラスを生成できます。このツールは、CMakeのQt6::ProtobufTools パッケージによって提供されています。これは、Googleのprotoc ツールの拡張機能として動作します。

find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)

使用方法

Qt には、qtprotobufgen ツールの使用を容易にする CMake 関数が用意されています。ビルドツールとして CMake を使用する場合は、Qt CMake API の使用を推奨します。CMake 以外のビルドシステムを使用する場合は、「手動での実行」に記載されているコマンドを適宜調整してください。

CMake

以下のCMakeコマンドを実行すると、protobufスキーマをQtプロジェクトに組み込むことができます。

通常、qtprotobufgen は、qt_add_protobuf マクロを使用してCMake経由で呼び出されます。

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 ライブラリにリンクします。

手動での実行

protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen \
    --qtprotobuf_out="[<options>:]<output_dir>" \
    [--qtprotobuf_opt="<options>"] \
    [-I/extra/proto/include/path] \
    <protofile>.proto

options 引数は、セミコロンで区切られたOptionsのリストです。これは2つの異なる方法で指定できます。 output_dir引数のオプションの前に、コロンで区切って付加する方法。あるいは、--qtprotobuf_opt という別の引数として指定する方法です。また、対応するキーをQT_PROTOBUF_OPTIONS 環境変数として指定することもできます。キーはセミコロン区切りのリストとして指定する必要があります：

export QT_PROTOBUF_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

オプション

このジェネレータは、生成の調整に指定できるオプションをサポートしています。オプションには、qt_add_protobuf関数内で直接使用できるエイリアスがあります。以下のオプションがサポートされています:

• COPY_COMMENTS .proto ファイルのコメントを生成されたコードにコピーします。
• GENERATE_PACKAGE_SUBFOLDERS .proto ファイルのパッケージ名指定子を使用して、生成されたファイルのフォルダ構造を作成します。たとえば、パッケージが として定義されている場合、生成されたファイルはpackage io.qt.testOUTPUT_DIRECTORY/io/qt/test/に配置されます。
• EXPORT_MACRO 生成されたコードで使用されるエクスポートマクロのベース名を定義します。最終的なマクロ名はQPB_<EXPORT_MACRO>_EXPORT の形式で構成されます。このオプションが設定されていない場合、エクスポートマクロは生成されません。

  Qt 6.8 以降、次の形式がサポートされています:EXPORT_MACRO=macro_name[:macro_output_file[:<true|false>]] 。この形式を使用すると、エクスポートマクロを含むヘッダーファイルの名前を指定し、その生成の有無を明示的に制御することができます。

  注: <macro_output_file>が指定されていない場合 、このオプションのデフォルトは以前の構文になります。

• 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』を参照してください。