Das Tool „qtprotobufgen“

Mit dem Tool „ qtprotobufgen “ lassen sich „ Qt Protobuf “-Klassen aus einem Protobuf-Schema generieren. Das Tool wird vom CMake-Paket „ Qt6::ProtobufTools “ bereitgestellt. Es fungiert als Erweiterung des Google-Tools „ protoc “.

find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)

Verwendung

Qt stellt CMake-Funktionen bereit, die die Verwendung des Tools „ qtprotobufgen “ vereinfachen. Wenn Sie CMake als Build-Tool verwenden, sollten Sie vorzugsweise die Qt-CMake-API nutzen. Für andere Build-Systeme als CMake passen Sie die unter „Manuelle Ausführung“ beschriebenen Befehle entsprechend an.

CMake

Die folgenden CMake-Befehle binden ein Protobuf-Schema in ein Qt-Projekt ein.

In der Regel wird „ qtprotobufgen “ über CMake mithilfe des Makros „ qt_add_protobuf “ aufgerufen.

Verwendung von `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)

Im obigen Beispiel generieren wir eine Bibliothek namens „ MyMessages “, die die Nachrichtentypen enthält, die in den an die Option „ PROTO_FILES “ übergebenen Pfaden definiert sind. Die Option „ GENERATE_PACKAGE_SUBFOLDERS “ dient dazu, eine Ordnerstruktur für die generierten Dateien zu erstellen. Und die Option „ PROTO_INCLUDES “ weist „protoc“ an, in den angegebenen Verzeichnissen nach Abhängigkeiten oder Importen zu suchen. Wir erstellen ein Ziel für eine ausführbare Datei namens „ MyApp “, die wir mit der Bibliothek „ MyMessages “ verknüpfen.

Manuelle Ausführung

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

Das Argument „ options “ ist eine durch Semikolons getrennte Liste von Optionen. Es kann auf zwei verschiedene Arten übergeben werden. Entweder durch Voranstellen der Optionen an das Argument `output_dir`, getrennt durch einen Doppelpunkt. Oder über ein separates Argument: ` --qtprotobuf_opt`. Sie können die entsprechenden Schlüssel auch als Umgebungsvariable ` QT_PROTOBUF_OPTIONS ` übergeben. Die Schlüssel müssen als durch Semikolons getrennte Liste angegeben werden:

export QT_PROTOBUF_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

Optionen

Der Generator unterstützt Optionen, mit denen die Generierung angepasst werden kann. Die Optionen haben direkte Aliase in der Funktion ` qt_add_protobuf `. Die folgenden Optionen werden unterstützt:

• COPY_COMMENTS Kopiert Kommentare aus den ` .proto `-Dateien in den generierten Code.
• GENERATE_PACKAGE_SUBFOLDERS verwendet den Paketnamen aus den „ .proto “-Dateien, um die Ordnerstruktur für die generierten Dateien zu erstellen. Wenn das Paket beispielsweise wie folgt definiert ist: ` package io.qt.test`, werden die generierten Dateien in `OUTPUT_DIRECTORY/io/qt/test/` abgelegt .
• EXPORT_MACRO definiert den Basisnamen für das im generierten Code verwendete Export-Makro. Der endgültige Makroname wird wie folgt gebildet: „ QPB_<EXPORT_MACRO>_EXPORT “. Ist diese Option nicht gesetzt, wird kein Export-Makro generiert.

  Seit Qt 6.8 wird das folgende Format unterstützt: EXPORT_MACRO=macro_name[:macro_output_file[:<true|false>]]. Mit diesem Format können Sie den Namen der Header-Datei angeben, die das Export-Makro enthält, und explizit steuern, ob es generiert wird.

  Hinweis: Wenn <macro_output_file> nicht angegeben wird, wird standardmäßig die bisherige Syntax verwendet.

• HEADER_GUARD Legt den Mechanismus fest, der verwendet wird, um generierte Header-Dateien vor mehrfacher Einbindung zu schützen. Mögliche Werte sind pragma und filename. Der Standardwert ist filename. Wenn die Option auf pragma gesetzt wird, wird der moderne Pragma-Header-Guard generiert:

  #pragma once
  ...

  Wird die Option weggelassen oder auf „ filename “ gesetzt, wird der „ ifdef “-Wrapping-Guard generiert und der Dateiname „.proto“ als Guard-Infix verwendet:

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

  Wählen Sie den bevorzugten Guard-Stil entsprechend Ihrer Projektstruktur aus.

• GENERATE_NON_FINAL_MESSAGES (seit Qt 6.11) generiert „ QtProtobuf “-Nachrichtenklassen ohne den Spezifizierer „ final “. Diese Option dient der Abwärtskompatibilität. Seit Qt 6.11 werden „ QtProtobuf “-Nachrichtenklassen standardmäßig als „ final “ generiert. Um das Verhalten generierter Nachrichten zu erweitern, sollten Sie Komposition gegenüber Vererbung bevorzugen. Diese Option wird in Qt 7 entfernt.
• GENERATE_NON_FINAL_PROPERTIES (seit Qt 6.12) generiert Eigenschaften von „ QtProtobuf “-Nachrichtenklassen ohne den Spezifizierer „ FINAL “. Der Spezifizierer „ FINAL “ ermöglicht es den QML-Entwicklungswerkzeugen, Leistungsoptimierungen anzuwenden und effizienteren Code zu generieren. Seit Qt 6.12 werden Eigenschaften von „ QtProtobuf “-Meldungsklassen standardmäßig mit dem Spezifizierer „ FINAL “ generiert. Diese Option dient ausschließlich der Abwärtskompatibilität und wird in Qt 7 entfernt. Weitere Informationen zum Spezifizierer „ FINAL “ finden Sie unter „Qt Property System“.