L'outil qtprotobufgen

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

find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)

Utilisation

Qt fournit des fonctions CMake qui facilitent l'utilisation de l'outil qtprotobufgen. Lorsque vous utilisez CMake comme outil de construction, vous devriez préférer utiliser l'API CMake de Qt. Pour les systèmes de construction autres que CMake, adaptez les commandes décrites dans Exécuter manuellement.

CMake

Les commandes CMake suivantes intègrent un schéma Protobuf dans un projet Qt.

Habituellement, qtprotobufgen est invoqué par CMake à l'aide de la macro qt_add_protobuf.

Utilisation de 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)

Dans l'exemple ci-dessus, nous générons une bibliothèque appelée MyMessages, qui contient les types de messages définis dans les chemins passés à l'option PROTO_FILES. L'option GENERATE_PACKAGE_SUBFOLDERS permet de générer une structure de dossiers pour les fichiers générés. L'option PROTO_INCLUDES indique à protoc de rechercher des dépendances ou des importations dans les répertoires spécifiés. Nous créons une cible pour un exécutable appelé MyApp, que nous lions à la bibliothèque MyMessages.

Exécution manuelle

protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen \
    --qtprotobuf_out="[<options>:]<output_dir>" \
    [--qtprotobuf_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 de deux manières différentes. Soit en ajoutant les options à l'argument output_dir, délimitées par deux points. Soit par l'intermédiaire d'un argument séparé, --qtprotobuf_opt. Vous pouvez également transmettre les clés correspondantes en tant que variable d'environnement QT_PROTOBUF_OPTIONS. Les clés doivent être présentées sous la forme d'une liste séparée par des points-virgules :

export QT_PROTOBUF_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

Options

Le générateur supporte des options qui peuvent être fournies pour affiner la génération. Les options ont des alias directs dans la fonction qt_add_protobuf. 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.

• GENERATE_NON_FINAL_MESSAGES génère les classes de messages QtProtobuf sans le spécificateur final. Cette option est fournie à des fins de compatibilité ascendante. Depuis Qt 6.11, les classes de messages QtProtobuf sont générées comme final par défaut. Pour étendre le comportement des messages générés, préférez la composition à l'héritage. Cette option sera supprimée dans Qt7.