qt_add_protobuf

Génère du code source C++ basé sur Qt à partir d'un schéma Protobuf.

Cette commande est définie dans le composant Protobuf du paquet Qt6. Chargez le paquet à l’aide de la commande suivante :

find_package(Qt6 REQUIRED COMPONENTS Protobuf)

Cette commande a été introduite dans Qt 6.5.

Utilisez qt_add_protobuf pour appeler qtprotobufgen dans vos scripts CMake et générer le code à partir des schémas .proto de vos projets.qtprotobufgen serait appelé via CMake à l'aide de la commande qt_add_protobuf.

Syntaxe

qt_add_protobuf(<target>
    PROTO_FILES <file> ...
    [PROTO_INCLUDES <path> ...]
    [QML [QML_URI <uri>]]
    [OUTPUT_DIRECTORY <dir>]
    [GENERATE_PACKAGE_SUBFOLDERS]
    [COPY_COMMENTS]
    [EXPORT_MACRO <infix>]
    [OUTPUT_HEADERS <var>]
    [OUTPUT_TARGETS <var>]
    [HEADER_GUARD <pragma|filename>]
    [GENERATE_NON_FINAL_MESSAGES] # since Qt 6.11
    [GENERATE_NON_FINAL_PROPERTIES] # since Qt 6.12
)

Si les commandes sans version sont désactivées, utilisez plutôt qt6_add_protobuf(). Elle prend en charge le même ensemble d’arguments que cette commande.

Description

Les fichiers source générés par qtprotobufgen sont ensuite ajoutés à la cible. Si la cible existe déjà, les fichiers générés sont ajoutés à la liste des sources de la cible. Si la cible n’existe pas, elle est créée sous forme de bibliothèque à laquelle vous devez lier votre code.

• PROTO_FILES spécifie la liste des fichiers .proto utilisés par la procédure de génération de code.
• PROTO_INCLUDES spécifie la liste des répertoires à parcourir pour rechercher les dépendances protobuf.

  Remarque : l’emplacement de ` PROTO_FILES ` est implicitement considéré comme faisant partie du chemin d’inclusion protobuf.

• QML active la génération de types de messages compatibles QML à partir de définitions Protobuf et les enregistre en tant que module QML. Si la fonction ` qt_add_protobuf ` est appelée sur une cible inexistante ou sur une cible qui n’est pas un module QML, un nouveau module QML sera créé implicitement.

  find_package(Qt6 6.8 REQUIRED COMPONENTS Quick Protobuf ProtobufQuick)
  ...
  qt_add_executable(target
      ...
  )
  // creates a new QML module
  qt_add_protobuf(target
      QML
      ...
  )

  Si `target` est un module QML existant, ` qt_add_protobuf ` associera les types protobuf générés à ce module.

  find_package(Qt6 6.8 REQUIRED COMPONENTS Quick Protobuf ProtobufQuick)
  ...
  qt_add_qml_module(target
      ...
  )
  // adds to existing QML module
  qt_add_protobuf(target
      QML
      ...
  )

  Remarque : si vous utilisez l’argument QML, vous devez ajouter ProtobufQuick dans l’appel à find_package. Voir les exemples ci-dessus.

• QML_URI définit l'URI utilisé pour le module QML.

  Chaque module QML doit définir une « URI », qui est utilisée dans les instructions d'importation pour exposer ses types Protobuf à QML.

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

  Si l'QML_URI est omis, le nom du paquet protobuf sera utilisé comme URI du module.

  Remarque : si l'QML_URI est omis, tous les fichiers .proto spécifiés dans la section PROTO_FILES doivent partager le même nom de paquet protobuf, car celui-ci sera utilisé comme URI par défaut pour le module QML résultant.

  Remarque : vous devez éviter de créer plusieurs modules QML protobuf avec le même nom d’ QML_URI ou de package proto, car cela entraîne une erreur d’importation dans le contexte QML.

  Remarque : si l'QML_URI est transmise à la fonction qt_add_protobuf, mais que la cible existe déjà, l'argument QML_URI sera ignoré.

  Consultez la section Modules identifiés pour une analyse plus approfondie de l’argument ` URI`.

• OUTPUT_DIRECTORY définit le répertoire dans lequel les fichiers générés seront placés. Par défaut, c’est le répertoire de compilation actuel qui est utilisé.
• 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/.
• COPY_COMMENTS copie les commentaires des fichiers ` .proto ` dans le code généré.
• EXPORT_MACRO S'applique uniquement lors de la création d'une nouvelle bibliothèque partagée à partir de <target>. Cette option spécifie 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, le nom de la cible est utilisé sous la forme EXPORT_MACRO.

  Consultez la section Création de bibliothèques partagées pour plus d’informations détaillées.

• OUTPUT_HEADERS Spécifie une variable qui stockera la liste des en-têtes générés. Cette liste peut être utile pour définir des règles d’installation de projet personnalisées.
• OUTPUT_TARGETS Spécifie une variable qui stockera la liste des cibles générées. Cette liste peut être utile pour définir des règles d’installation personnalisées pour le projet.
• 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, 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’enveloppement « 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 des messages « 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 le système de propriétés Qt.

Résolution des dépendances entre les cibles protobuf

La commande « qt_add_protobuf » ne prend pas en compte les dépendances entre les fichiers « .proto » utilisés pour générer du code destiné à différentes cibles.

Le projet peut comporter deux fichiers « .proto » ou plus présentant des dépendances :

// test_messages.proto
syntax = "proto3";

package test.messages;

message MyMessage {
    int32 myField = 1;
}

// test_extensions.proto
syntax = "proto3";

import "test_messages.proto";

package test.extensions;

message MyExtension {
    test.messages.MyMessage baseMessage = 1;
    int32 extension = 2;
}

Les fichiers « .proto » ci-dessus peuvent être utilisés pour générer les bibliothèques autonomes :

qt_add_protobuf(test_messages
    PROTO_FILES
        test_messages.proto
)
...
qt_add_protobuf(test_extensions
    PROTO_FILES
        test_extensions.proto
)
...

Étant donné que la cible « test_extensions » dépend des messages provenant de la cible « test_messages », vous devez lier manuellement ces cibles dans vos scripts « CMake » :

target_link_libraries(test_extensions PUBLIC test_messages)

Exemple

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. Et l’option PROTO_INCLUDES 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.

Exemple QML étendu avec protobuf

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

find_package(Qt6 REQUIRED COMPONENTS Protobuf ProtobufQuick Quick)
qt_standard_project_setup()

qt_add_protobuf(MyMessagesPlugin
    QML
    QML_URI my.messages.module.uri
    PROTO_FILES
        path/to/message.proto
        path/to/other_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_protobuf(MyApp
    QML
    PROTO_FILES
        path/to/internal_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_qml_module(MyApp
    URI example.uri
    VERSION 1.0
    QML_FILES qml/main.qml
)

qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Quick)

Dans l’exemple QML étendu ci-dessus, lors du premier appel à ` qt_add_protobuf `, nous générons un module QML nommé ` MyMessagesPlugin`, qui contient les types de messages définis dans les chemins transmis à l’option ` PROTO_FILES `. Nous utilisons l’option QML, qui permet l’enregistrement des types de messages protobuf dans le contexte QML. Les types enregistrés seront disponibles dans QML en important un chemin défini par l’option QML_URI. Lors du deuxième appel à qt_add_protobuf, nous ajoutons du code généré automatiquement au module QML existant MyApp. L’option QML_URI n’est pas requise dans ce cas. Enfin, nous créons une cible pour un exécutable nommé MyApp, qui dispose d’un module QML pour la partie graphique et charge MyMessagesPlugin dans le fichier main.qml via l’importation my.messages.module.uri.

Installation de la bibliothèque autonome Qt Protobuf

La commande ` qt_add_protobuf ` génère également des listes d’artefacts pour une installation ultérieure. Vous pouvez consulter ces artefacts en spécifiant les arguments ` OUTPUT_HEADERS` et ` OUTPUT_TARGETS ` comme suit :

qt_add_protobuf(MyProtoLib
    PROTO_FILES
        mylib.proto
    OUTPUT_HEADERS
        public_headers
    OUTPUT_TARGETS
        generated_targets
)

La commande stocke la liste des fichiers d’en-tête et des cibles générés par la commande ` qt_add_protobuf ` respectivement dans les variables ` public_headers ` et ` generated_targets `.

Utilisez la commande standard CMake ` install ` pour installer les artefacts et générer les fichiers ` config ` pour votre bibliothèque :

include(GNUInstallDirs)
set_target_properties(MyProtoLib PROPERTIES
    PUBLIC_HEADER
        "${public_headers}"
    INTERFACE_INCLUDE_DIRECTORIES
        "$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}>"
)
install(TARGETS ${generated_targets} EXPORT MyProtoLibTargets
    PUBLIC_HEADER
        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
)
install(EXPORT MyProtoLibTargets NAMESPACE MyProtoLib:: DESTINATION lib/cmake/MyProtoLib)

Utilisez ensuite la configuration « MyProtoLibTargets » générée dans le fichier de configuration du paquet. Pour en savoir plus sur le processus de création de paquets, consultez la documentation officielle de CMake.

Une fois installée, la bibliothèque est disponible sous forme de paquet CMake autonome :

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE MyProtoLib::MyProtoLib Qt6::Protobuf)