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_FILESespecifica la lista de archivos .proto utilizados por el procedimiento de generación de código.PROTO_INCLUDESEspecifica la lista de directorios en los que se buscarán las dependencias de Protobuf.Nota: La ubicación de
PROTO_FILESse considera implícitamente parte de la ruta de inclusión de protobuf.QMLHabilita 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_URIdefine elURIutilizado 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_URIo nombre de paquete proto, ya que esto provoca un error de importación en el contexto de QML.Nota: Si se pasa
QML_URIa la funciónqt_add_protobuf, pero el destino ya existe, se ignorará el argumentoQML_URI.Consulte «Módulos identificados » para obtener información más detallada sobre `
URI`.OUTPUT_DIRECTORYdefine el directorio en el que se colocarán los archivos generados. Por defecto, se utiliza el directorio de compilación actual.GENERATE_PACKAGE_SUBFOLDERSUtiliza 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_COMMENTScopia los comentarios de los archivos.protoal código generado.EXPORT_MACROSe 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 comoQPB_<EXPORT_MACRO>_EXPORT. Si no se establece esta opción, se utiliza el nombre del destino comoEXPORT_MACRO.Consulta «Creación de bibliotecas compartidas » para obtener información más detallada.
OUTPUT_HEADERSEspecifica una variable que almacenará la lista de encabezados generados. Esta lista puede resultar útil para definir reglas de instalación personalizadas del proyecto.OUTPUT_TARGETSEspecifica una variable que almacenará la lista de objetivos generados. Esta lista puede resultar útil para definir reglas de instalación personalizadas del proyecto.HEADER_GUARDespecifica el mecanismo utilizado para evitar la inclusión múltiple de los archivos de cabecera generados. Los valores posibles sonpragmayfilename. El valor por defecto esfilename. Si se establece la opción enpragma, 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 envolturaifdefy se utiliza el nombre de archivo «.proto» como infijo de protección:#ifdef MYMESSAGES_QPB_H #define MYMESSAGES_QPB_H ... #endif // MYMESSAGES_QPB_HSelecciona 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 especificadorFINAL. 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.