L'outil qtgrpcgen

L'outil qtgrpcgen permet de générer des classes de service d'Qt GRPC à partir d'un schéma protobuf. Cet outil est fourni par le paquet 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 compilation, il est préférable d'utiliser l'API CMake de Qt. Pour les systèmes de compilation autres que CMake, vous pouvez adapter les commandes décrites dans la section Exécution manuelle de qtgrpcgen.

CMake

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

En général, qtgrpcgen est appelé via 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 de code ` Qt GRPC ` pour les sections ` service ` du schéma protobuf fourni.

Comme nous réutilisons la cible « executable », tous les fichiers générés seront ajoutés à cette cible, et les répertoires d’inclusion seront mis à jour en conséquence.

Exécution manuelle de l'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é par deux points, ou via un argument distinct, ` --qtgrpc_opt`. Vous pouvez également transmettre les clés correspondantes via la 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 permettant d’ajuster la génération. Ces options ont des alias directs dans la fonction `qt_add_grpc`. Les options suivantes sont prises en charge :

• COPY_COMMENTS copie les commentaires des fichiers ` .proto ` dans le code généré.
• GENERATE_PACKAGE_SUBFOLDERS utilise le spécificateur de nom de paquet issu des fichiers ` .proto ` pour créer la structure de dossiers des fichiers générés. Par exemple, si le paquet est défini comme suit : ` 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 sous la forme 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 celle-ci doit être générée.

  Remarque : si <macro_output_file> n’est pas fourni, l’option utilise par défaut la syntaxe précédente.

• HEADER_GUARD Spécifie le mécanisme utilisé pour empêcher l’inclusion multiple des fichiers d’en-tête générés. Les valeurs possibles sont pragma et filename. La valeur par défaut est filename. Définir cette option sur pragma génère la protection d’en-tête pragma moderne :

  #pragma once
  ...

  Si l’option est omise ou définie sur filename, la protection d’encapsulation ifdef est générée, et le nom de fichier « .proto » est utilisé comme infixe de protection :

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

  Choisissez le style de garde qui convient le mieux à la structure de votre projet.

• QML active la génération d’un client QML pour le service gRPC.