L'outil qtgrpcgen

L'outil qtgrpcgen peut être utilisé pour générer des classes de service Qt GRPC à partir d'un schéma protobuf. L'outil est fourni par le paquetage CMake Qt6::GrpcTools. Il fonctionne comme une extension de l'outil protoc de Google.

find_package(Qt6 COMPONENTS GrpcTools REQUIRED)

Utilisation

Qt fournit des fonctions CMake qui facilitent l'utilisation de l'outil qtgrpcgen. Lorsque vous utilisez CMake comme outil de construction, il est préférable d'utiliser l'API CMake de Qt. Pour les systèmes de construction autres que CMake, vous pouvez ajuster les commandes décrites dans Running qtgrpcgen manuellement.

CMake

Les commandes CMake suivantes permettent d'intégrer un service gRPC dans un projet Qt.

Habituellement, qtgrpcgen est invoqué par CMake à l'aide de la macro qt_add_grpc, comme le montre l'exemple suivant :

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)

L'exemple ci-dessus appelle la fonction CMake qt_add_grpc() pour lancer la génération du code Qt GRPC pour les sections service dans le schéma protobuf fourni.

Comme nous réutilisons la cible exécutable, tous les fichiers générés seront ajoutés à la cible et les répertoires include seront mis à jour en conséquence.

Exécution manuelle de qtgrpcgen

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

L'argument options est une liste d'options séparées par des points-virgules. Il peut être transmis en ajoutant options à l'argument --qtgrpc_out, séparés par deux points, ou par un argument séparé, --qtgrpc_opt. Vous pouvez également transmettre les clés correspondantes en tant que variable d'environnement QT_GRPC_OPTIONS. Les clés doivent être présentées sous la forme d'une liste séparée par des points-virgules :

export QT_GRPC_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

Options

Le générateur prend en charge des options qui peuvent être fournies pour affiner la génération. Les options ont des alias directs dans la fonction qt_add_grpc. Les options suivantes sont supportées :

• COPY_COMMENTS copie les commentaires des fichiers .proto dans le code généré.
• GENERATE_PACKAGE_SUBFOLDERS utilise le nom du paquetage spécifié dans les fichiers .proto pour créer la structure du dossier pour les fichiers générés. Par exemple, si le paquetage est défini comme : package io.qt.test les fichiers générés seront placés dans OUTPUT_DIRECTORY/io/qt/test/.
• EXPORT_MACRO définit le nom de base de la macro d'exportation utilisée dans le code généré. Le nom final de la macro est construit comme QPB_<EXPORT_MACRO>_EXPORT. Si cette option n'est pas définie, aucune macro d'exportation n'est générée.

  Depuis Qt 6.8, le format suivant est pris en charge : EXPORT_MACRO=macro_name[:macro_output_file[:<true|false>]]. Ce format vous permet de spécifier le nom du fichier d'en-tête contenant la macro d'exportation et de contrôler explicitement si elle est générée.

  Remarque : si <fichier_de_sortie_de_macro> n'est pas fourni, l'option reprend par défaut la syntaxe précédente.

• HEADER_GUARD spécifie le mécanisme utilisé pour protéger les fichiers d'en-tête générés contre l'inclusion multiple. Les valeurs possibles sont pragma, filename. La valeur par défaut est filename. La définition de l'option à pragma génère le pragma header guard moderne :

  #pragma once
  ...

  L'omission de l'option ou la définition de l'option à filename génère le mécanisme de protection ifdef et utilise le nom de fichier '.proto' comme infixe de protection :

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

  Sélectionnez le style de garde préféré en fonction de la structure de votre projet.

• QML permet de générer un client QML pour le service gRPC.