Das Werkzeug qtprotobufgen

Das Tool qtprotobufgen kann verwendet werden, um Qt Protobuf Klassen aus einem Protobuf-Schema zu generieren. Das Werkzeug wird vom CMake-Paket Qt6::ProtobufTools bereitgestellt. Es funktioniert als eine Erweiterung des protoc Werkzeugs von Google.

find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)

Verwendung

Qt stellt CMake-Funktionen bereit, die die Verwendung des Tools qtprotobufgen erleichtern. Wenn Sie CMake als Build-Tool verwenden, sollten Sie die Qt CMake API verwenden. Für andere Build-Systeme als CMake passen Sie die unter Manuelles Ausführen beschriebenen Befehle an.

CMake

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

Normalerweise wird qtprotobufgen über CMake mit dem Makro 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 erzeugen wir eine Bibliothek namens MyMessages, die die Nachrichtentypen enthält, die in den Pfaden definiert sind, die der Option PROTO_FILES übergeben wurden. Die Option GENERATE_PACKAGE_SUBFOLDERS generiert eine Ordnerstruktur für die erzeugten Dateien. 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 Semikolon getrennte Liste von Optionen. Sie kann auf zwei verschiedene Arten übergeben werden. Entweder durch Voranstellen der Optionen an das Argument output_dir, begrenzt durch einen Doppelpunkt. Oder durch 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 eine durch Semikolon getrennte Liste angegeben werden:

export QT_PROTOBUF_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

Optionen

Der Generator unterstützt Optionen, die zur Abstimmung der Generierung angegeben werden können. 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. Zum Beispiel, wenn das Paket definiert ist als: 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 Exportmakro. Der endgültige Makroname wird wie QPB_<EXPORT_MACRO>_EXPORT aufgebaut. Wenn diese Option nicht gesetzt ist, wird kein Exportmakro erzeugt.

  Seit Qt 6.8 wird das folgende Format unterstützt: EXPORT_MACRO=macro_name[:macro_output_file[:<true|false>]]. Dieses Format erlaubt es Ihnen, den Namen der Header-Datei anzugeben, die das Exportmakro enthält, und explizit zu steuern, ob es generiert wird.

  Hinweis: Wenn <macro_output_file> nicht angegeben wird, wird die Option auf die vorherige Syntax zurückgesetzt.

• HEADER_GUARD gibt den Mechanismus an, der verwendet wird, um generierte Header-Dateien vor mehrfacher Einbindung zu schützen. Mögliche Werte sind pragma, filename. Der Standardwert ist filename. Wenn Sie die Option auf pragma setzen, wird das moderne pragma header guard erzeugt:

  #pragma once
  ...

  Das Weglassen der Option oder das Setzen der Option auf filename erzeugt den ifdef Wrapping Guard und verwendet den Dateinamen '.proto' als Guard-Infix:

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

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