Das Tool „qtgrpcgen“

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

find_package(Qt6 COMPONENTS GrpcTools REQUIRED)

Verwendung

Qt stellt CMake-Funktionen bereit, die die Verwendung des Tools „ qtgrpcgen “ vereinfachen. Wenn Sie CMake als Build-Tool verwenden, empfiehlt es sich, die Qt-CMake-API zu nutzen. Für andere Build-Systeme als CMake können Sie die im Abschnitt „Manuelle Ausführung von qtgrpcgen“ beschriebenen Befehle anpassen.

CMake

Die folgenden CMake-Befehle integrieren einen „ gRPC “-Dienst in ein Qt-Projekt.

Normalerweise wird „ qtgrpcgen “ über CMake mithilfe des Makros „ qt_add_grpc “ aufgerufen, wie im folgenden Beispiel gezeigt:

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

find_package(Qt6 REQUIRED COMPONENTS Protobuf Grpc)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)

qt_add_protobuf(MyApp
    PROTO_FILES
        path/to/messages.proto
)

qt_add_grpc(MyApp CLIENT
    PROTO_FILES
        path/to/service.proto
)

target_link_libraries(MyApp PRIVATE Qt6::Protobuf Qt6::Grpc)

Das obige Beispiel ruft die CMake-Funktion „ qt_add_grpc() “ auf, um die Code-Generierung mit „ Qt GRPC “ für die Abschnitte „ service “ innerhalb des angegebenen Protobuf-Schemas zu starten.

Da wir das ausführbare Ziel wiederverwenden, werden alle generierten Dateien an das Ziel angehängt und die Include-Verzeichnisse entsprechend aktualisiert.

qtgrpcgen manuell ausführen

protoc --plugin=protoc-gen-qtgrpc=<path/to/bin/>qtgrpcgen \
    --qtgrpc_out="[<options>:]<output_dir>" \
    [--qtgrpc_opt="<options>"] \
    [-I/extra/proto/include/path] \
    <protofile>.proto

Das Argument „ options “ ist eine durch Semikolons getrennte Liste von Optionen. Es kann übergeben werden, indem „ options “ durch einen Doppelpunkt getrennt an das Argument „ --qtgrpc_out “ angehängt wird, oder über ein separates Argument: „ --qtgrpc_opt “. Sie können die entsprechenden Schlüssel auch als Umgebungsvariable „ QT_GRPC_OPTIONS “ übergeben. Die Schlüssel müssen als durch Semikolons getrennte Liste angegeben werden:

export QT_GRPC_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_grpc`. 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 “. Wenn diese Option nicht gesetzt ist, 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, mit dem generierte Header-Dateien vor mehrfacher Einbindung geschützt werden. 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.

• QML Aktiviert die Generierung eines QML-Clients für den Dienst „ gRPC “.