L'outil qtprotobufgen

L'outil qtprotobufgen permet de générer des classes d'Qt Protobuf s à partir d'un schéma protobuf. Cet 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 compilation, il est recommandé de privilégier l'API CMake de Qt. Pour les systèmes de compilation autres que CMake, adaptez les commandes décrites dans la section « Exécution manuelle ».

CMake

Les commandes CMake suivantes permettent d'intégrer un schéma Protobuf dans un projet Qt.

En général, la commande ` qtprotobufgen ` est exécutée via 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 nommé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. Quant à l’option PROTO_INCLUDES, elle indique à protoc de rechercher les dépendances ou les importations dans les répertoires spécifiés. Nous créons une cible pour un exécutable nommé 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 passé de deux manières différentes. Soit en les ajoutant au début de l’argument `output_dir`, délimitées par deux points. Soit via un argument distinct, ` --qtprotobuf_opt`. Vous pouvez également passer les clés correspondantes via la 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 prend en charge des options permettant d’ajuster la génération. Ces options ont des alias directs dans la fonction ` qt_add_protobuf `. 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 provenant 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. Si l’option est définie sur pragma, cela 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.

• GENERATE_NON_FINAL_MESSAGES (depuis Qt 6.11) génère des classes de messages de type « QtProtobuf » sans le spécificateur « final ». Cette option est fournie à des fins de compatibilité ascendante. Depuis Qt 6.11, les classes de messages de type « QtProtobuf » sont générées par défaut sous la forme « final ». Pour étendre le comportement des messages générés, privilégiez la composition plutôt que l’héritage. Cette option sera supprimée dans Qt 7.
• GENERATE_NON_FINAL_PROPERTIES (depuis Qt 6.12) génère les propriétés des classes de messages « QtProtobuf » sans le spécificateur « FINAL ». Le spécificateur « FINAL » permet aux outils QML d’appliquer des optimisations de performances et de générer un code plus efficace. Depuis Qt 6.12, les propriétés de messages de type « QtProtobuf » sont générées par défaut avec le spécificateur « FINAL ». Cette option est fournie uniquement à des fins de compatibilité ascendante et sera supprimée dans Qt 7. Pour plus d’informations sur le spécificateur « FINAL », consultez la section Système de propriétés Qt.