qt_add_protobuf

Genera código fuente C++ basado en Qt utilizando un esquema protobuf.

El comando está definido en el componente Protobuf del paquete Qt6. Carga el paquete con:

find_package(Qt6 REQUIRED COMPONENTS Protobuf)

Este comando se introdujo en Qt 6.5.

Utilice qt_add_protobuf para invocar qtprotobufgen en sus scripts CMake y generar el código de los esquemas .proto para sus proyectos.qtprotobufgen se invocaría a través de CMake utilizando el comando qt_add_protobuf.

Sinopsis

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]
)

Si los comandos versionless están deshabilitados, utilice qt6_add_protobuf() en su lugar. Admite el mismo conjunto de argumentos que este comando.

Descripción

Los archivos fuente generados por qtprotobufgen se añaden al objetivo. Si el destino ya existe, los archivos generados se añaden a la lista de fuentes del destino. Si el objetivo no existe, se crea como una biblioteca con la que debe enlazar.

• PROTO_FILES especifica la lista de archivos .proto utilizados por el procedimiento de generación de código.
• PROTO_INCLUDES especifica la lista de directorios en los que buscar dependencias protobuf.

  Nota: La ubicación de PROTO_FILES se considera implícitamente parte de la ruta de inclusión de protobuf.

• QML permite la generación de tipos de mensaje compatibles con QML a partir de definiciones de protobuf y los registra como módulo QML. Si se llama a qt_add_protobuf en un objetivo inexistente o en un objetivo que no es un módulo QML, se creará implícitamente un nuevo módulo QML.

  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 el objetivo es un módulo QML existente, qt_add_protobuf adjuntará los tipos protobuf generados a ese módulo.

  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
      ...
  )

  Nota: Si utiliza el argumento QML, deberá añadir ProtobufQuick en la llamada find_package. Véanse los ejemplos anteriores.

• QML_URI define el URI utilizado para el módulo QML.

  Cada módulo QML debe definir un URI, que se utiliza en las sentencias import para exponer sus tipos protobuf a QML.

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

  Si se omite QML_URI, el nombre del paquete protobuf se utilizará como URI del módulo.

  Nota: Si se omite QML_URI, todos los archivos .proto especificados en la sección PROTO_FILES deben compartir el mismo nombre de paquete protobuf, ya que se utilizará como URI por defecto para el módulo QML resultante.

  Nota: Debe evitar crear varios módulos protobuf QML con el mismo QML_URI o nombre de paquete proto, porque da lugar a errores de importación en el contexto QML.

  Nota: Si se pasa QML_URI a la función qt_add_protobuf pero el objetivo ya existe, se ignorará el argumento QML_URI.

  Lea Módulos identificados para obtener más información sobre URI.

• OUTPUT_DIRECTORY define el directorio donde se colocarán los archivos generados. Por defecto, se utiliza el directorio de construcción actual.
• GENERATE_PACKAGE_SUBFOLDERS utiliza el especificador de nombre de paquete de los archivos .proto para crear la estructura de carpetas para los archivos generados. Por ejemplo, si el paquete se define como: package io.qt.test los archivos generados se colocarán en OUTPUT_DIRECTORY/io/qt/test/.
• COPY_COMMENTS copia los comentarios de los archivos .proto en el código generado.
• EXPORT_MACRO sólo se aplica al crear una nueva biblioteca compartida a partir del <target>. Esta opción especifica el nombre base para la macro de exportación utilizada en el código generado. El nombre final de la macro se construye como QPB_<EXPORT_MACRO>_EXPORT. Si no se establece esta opción, el nombre de destino se utiliza como EXPORT_MACRO.

  Lea Creación de bibliotecas compartidas para obtener más información en profundidad.

• OUTPUT_HEADERS especifica una variable que almacenará la lista de cabeceras generadas. Esta lista puede ser útil para definir reglas personalizadas de instalación del proyecto.
• OUTPUT_TARGETS especifica una variable que almacenará la lista de objetivos generados. Esta lista puede ser útil para definir reglas de instalación personalizadas.
• HEADER_GUARD especifica el mecanismo utilizado para proteger los archivos de cabecera generados de la inclusión múltiple. Los valores posibles son pragma, filename. Por defecto es filename. Establecer la opción a pragma genera el moderno pragma header guard:

  #pragma once
  ...

  Omitir la opción o establecerla en filename genera la protección de envoltura ifdef y utiliza el nombre de archivo '.proto' como infijo de protección:

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

  Seleccione el estilo de guardia preferido según la estructura de su proyecto.

• GENERATE_NON_FINAL_MESSAGES genera clases de mensajes QtProtobuf sin el especificador final. Esta opción se proporciona por compatibilidad con versiones anteriores. Desde Qt 6.11, las clases de mensajes QtProtobuf se generan como final por defecto. Para ampliar el comportamiento de los mensajes generados, prefiera la composición a la herencia. Esta opción se eliminará en Qt7.

Resolución de dependencias entre objetivos protobuf

El comando qt_add_protobuf no tiene en cuenta las dependencias entre archivos .proto que se utilizan para generar código para diferentes objetivos.

El proyecto puede tener dos o más archivos .proto con dependencias:

// 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;
}

Los archivos .proto anteriores pueden utilizarse para generar las bibliotecas independientes:

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

Dado que el objetivo test_extensions depende de los mensajes del objetivo test_messages, deberá enlazar manualmente con dichos objetivos en sus scripts CMake:

target_link_libraries(test_extensions PUBLIC test_messages)

Ejemplo

Uso 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)

En el ejemplo anterior, generamos una biblioteca llamada MyMessages, que contiene los tipos de mensaje definidos en las rutas pasadas a la opción PROTO_FILES. La opción GENERATE_PACKAGE_SUBFOLDERS para generar una estructura de carpetas para los archivos generados. Y la opción PROTO_INCLUDES le dice a protoc que busque dependencias o importaciones en los directorios especificados. Creamos un objetivo para un ejecutable llamado MyApp, que enlazamos con la biblioteca MyMessages.

Ejemplo de protobuf extendido QML

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)

En el ejemplo QML extendido anterior, mediante la primera llamada a qt_add_protobuf, generamos un módulo QML llamado MyMessagesPlugin, que contiene los tipos de mensaje definidos en las rutas pasadas a la opción PROTO_FILES. Utilizamos la opción QML, que habilita el registro de tipos de mensajes proto en el contexto QML. Los tipos registrados estarán disponibles en QML importando una ruta definida por QML_URI. Mediante una segunda llamada a qt_add_protobuf añadimos código autogenerado en el módulo QML existente MyApp. El QML_URI no es necesario en estos casos. Finalmente, creamos un objetivo para un ejecutable llamado MyApp, que tiene un módulo QML para la parte gráfica y carga MyMessagesPlugin en el archivo main.qml a través de la importación my.messages.module.uri.

Instalación de la biblioteca independiente Qt Protobuf

El comando qt_add_protobuf también produce listas de artefactos para su posterior instalación. Puede leer estos artefactos especificando los argumentos OUTPUT_HEADERS, y OUTPUT_TARGETS como se indica a continuación:

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

El comando almacena la lista de los archivos de cabecera y objetivos producidos por el comando qt_add_protobuf en las variables public_headers y generated_targets según corresponda.

Utilice el comando estándar de CMake install para instalar los artefactos y generar los archivos config para su biblioteca:

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)

A continuación, utiliza la configuración MyProtoLibTargets generada en el archivo de configuración del paquete. Puedes leer más sobre el proceso de creación de paquetes en la documentación oficial de CMake.

Después de la instalación de la biblioteca está disponible como el paquete independiente CMake:

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

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