En esta página

qt_add_protobuf

Genera código fuente en 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.

Utiliza `qt_add_protobuf` para invocar ` qtprotobufgen ` en tus scripts de CMake y generar el código a partir de los esquemas `.proto` de tus 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] # since Qt 6.11
    [GENERATE_NON_FINAL_PROPERTIES] # since Qt 6.12
)

Si los comandos sin versión están desactivados, 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 a continuación al destino. Si el destino ya existe, los archivos generados se añaden a la lista de fuentes del destino. Si el destino no existe, se crea como una biblioteca a la que debe vincularse.

  • 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 se buscarán las dependencias de Protobuf.

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

  • QML Habilita la generación de tipos de mensajes compatibles con QML a partir de definiciones de protobuf y los registra como un módulo QML. Si se llama a ` qt_add_protobuf ` sobre un destino inexistente o un destino 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 «target» es un módulo QML ya existente, « qt_add_protobuf » adjuntará los tipos protobuf generados a dicho 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 utilizas el argumento QML, debes añadir ProtobufQuick a la llamada a `find_package`. Consulta 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 de importación para exponer sus tipos Protobuf a QML.

    qt_add_protobuf(target
        QML
        QML_URI proto.uri.example
    )

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

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

    Nota: Se debe evitar crear varios módulos QML de protobuf con el mismo QML_URI o nombre de paquete proto, ya que esto provoca un error de importación en el contexto de QML.

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

    Consulte «Módulos identificados » para obtener información más detallada sobre ` URI`.

  • OUTPUT_DIRECTORY define el directorio en el que se colocarán los archivos generados. Por defecto, se utiliza el directorio de compilación actual.
  • GENERATE_PACKAGE_SUBFOLDERS Utiliza el especificador de nombre de paquete de los archivos « .proto » para crear la estructura de carpetas de 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 al código generado.
  • EXPORT_MACRO Se aplica únicamente al crear una nueva biblioteca compartida a partir de <target>. Esta opción especifica el nombre base de 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, se utiliza el nombre del destino como EXPORT_MACRO.

    Consulta «Creación de bibliotecas compartidas » para obtener información más detallada.

  • OUTPUT_HEADERS Especifica una variable que almacenará la lista de encabezados generados. Esta lista puede resultar útil para definir reglas de instalación personalizadas del proyecto.
  • OUTPUT_TARGETS Especifica una variable que almacenará la lista de objetivos generados. Esta lista puede resultar útil para definir reglas de instalación personalizadas del proyecto.
  • HEADER_GUARD especifica el mecanismo utilizado para evitar la inclusión múltiple de los archivos de cabecera generados. Los valores posibles son pragma y filename. El valor por defecto es filename. Si se establece la opción en pragma, se genera el pragma «header guard» moderno:
    #pragma once
    ...

    Si se omite la opción o se establece en filename, se genera la protección de envoltura ifdef y se utiliza el nombre de archivo «.proto» como infijo de protección:

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

    Selecciona el estilo de protección que prefieras en función de la estructura de tu proyecto.

  • GENERATE_NON_FINAL_MESSAGES (desde Qt 6.11) genera clases de mensajes de tipo « QtProtobuf » sin el especificador « final ». Esta opción se proporciona por motivos de compatibilidad con versiones anteriores. Desde Qt 6.11, las clases de mensajes de tipo « QtProtobuf » se generan como « final » de forma predeterminada. Para ampliar el comportamiento de los mensajes generados, es preferible utilizar la composición en lugar de la herencia. Esta opción se eliminará en Qt 7.
  • GENERATE_NON_FINAL_PROPERTIES (desde Qt 6.12) genera propiedades de clases de mensajes QtProtobuf sin el especificador FINAL. El especificador « FINAL » permite que las herramientas de QML apliquen optimizaciones de rendimiento y generen código más eficiente. Desde Qt 6.12, las propiedades de los mensajes « QtProtobuf » se generan con el especificador « FINAL » de forma predeterminada. Esta opción se proporciona únicamente por motivos de compatibilidad con versiones anteriores y se eliminará en Qt 7. Para obtener más información sobre el especificador « FINAL », consulta el Sistema de propiedades de Qt.

Resolución de dependencias entre destinos protobuf

El comando « qt_add_protobuf » no tiene en cuenta las dependencias entre los 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 se pueden utilizar 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 », es necesario vincular dichos objetivos manualmente en los scripts de « CMake »:

target_link_libraries(test_extensions PUBLIC test_messages)

Nota: Los mensajes del objetivo « test_messages » se utilizan en archivos de cabecera que pertenecen al objetivo « test_extensions », por lo que los objetivos que se vinculan a « test_extensions » deben tener el objetivo « test_messages » como dependencia transitiva. Se recomienda utilizar el ámbito de vinculación « PUBLIC » para disponer de las propiedades adecuadas « INTERFACE_INCLUDE_DIRECTORIES » y « INTERFACE_LINK_LIBRARIES » para los objetivos de la biblioteca protobuf.

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 mensajes definidos en las rutas pasadas a la opción PROTO_FILES. La opción GENERATE_PACKAGE_SUBFOLDERS sirve para generar una estructura de carpetas para los archivos generados. Y la opción PROTO_INCLUDES indica a protoc que busque dependencias o importaciones en los directorios especificados. Creamos un objetivo para un ejecutable llamado MyApp, que vinculamos a la biblioteca MyMessages.

Ejemplo de protobuf ampliado con 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 ampliado de QML anterior, mediante la primera llamada a ` qt_add_protobuf `, generamos un módulo QML llamado ` MyMessagesPlugin`, que contiene los tipos de mensajes definidos en las rutas pasadas a la opción ` PROTO_FILES `. Utilizamos la opción QML, que permite el registro de tipos de mensajes protobuf en el contexto QML. Los tipos registrados estarán disponibles en QML al importar una ruta establecida por QML_URI. Mediante la segunda llamada a qt_add_protobuf, añadimos código generado automáticamente al módulo QML existente MyApp. En estos casos, no es necesario utilizar QML_URI. Por último, creamos un objetivo para un ejecutable llamado MyApp, que cuenta con un módulo QML para la parte gráfica y carga MyMessagesPlugin en el archivo main.qml mediante la importación my.messages.module.uri.

Instalación de la biblioteca independiente « Qt Protobuf »

El comando ` qt_add_protobuf ` también genera listas de artefactos para su posterior instalación. Puedes consultar estos artefactos especificando los argumentos ` OUTPUT_HEADERS` y ` OUTPUT_TARGETS ` de la siguiente manera:

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

El comando almacena la lista de archivos de cabecera y objetivos generados por el comando ` qt_add_protobuf ` en las variables ` public_headers ` y ` generated_targets `, respectivamente.

Utiliza el comando estándar « install » de CMake para instalar los artefactos y generar los archivos « config » para tu 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 obtener más información sobre el proceso de creación de paquetes en la documentación oficial de CMake.

Tras la instalación, la biblioteca estará disponible como paquete independiente de CMake:

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

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

Nota: qt_add_protobuf no añade implícitamente Qt Protobuf el módulo como dependencia transitiva, ni para el objetivo « MyProtoLib » ni para el paquete CMake « MyProtoLib ». Por lo tanto, Qt Protobuf búsqueda del módulo y el enlace explícito de ` MyApp ` a ` Qt6::Protobuf ` son obligatorios.

Véase también La herramienta qtprotobufgen.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.