La herramienta qtprotobufgen

La herramienta qtprotobufgen puede utilizarse para generar clases Qt Protobuf a partir de un esquema protobuf. La herramienta es proporcionada por el paquete CMake Qt6::ProtobufTools. Funciona como una extensión de la herramienta protoc de Google.

find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)

Uso

Qt proporciona funciones CMake que facilitan el uso de la herramienta qtprotobufgen. Cuando utilices CMake como herramienta de compilación deberías preferir utilizar la API CMake de Qt. Para sistemas de compilación distintos de CMake, adapta los comandos descritos en Ejecutar manualmente.

CMake

Los siguientes comandos de CMake integran un esquema protobuf en un proyecto Qt.

Normalmente qtprotobufgen se invocaría a través de CMake utilizando la macro qt_add_protobuf.

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

Ejecutando manualmente

protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen \
    --qtprotobuf_out="[<options>:]<output_dir>" \
    [--qtprotobuf_opt="<options>"] \
    [-I/extra/proto/include/path] \
    <protofile>.proto

El argumento options es una lista de opciones separadas por punto y coma. Se puede pasar de dos maneras diferentes. O bien anteponiendo las opciones al argumento output_dir, delimitado por dos puntos. O a través de un argumento separado, --qtprotobuf_opt. También puede pasar las claves correspondientes como variable de entorno QT_PROTOBUF_OPTIONS. Las claves deben presentarse como una lista separada por punto y coma:

export QT_PROTOBUF_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

Opciones

El generador admite opciones que se pueden proporcionar para ajustar la generación. Las opciones tienen alias directos en la función qt_add_protobuf. Se admiten las siguientes opciones:

• COPY_COMMENTS copia los comentarios de los archivos .proto en el código generado.
• 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/.
• EXPORT_MACRO define 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 define esta opción, no se genera ninguna macro de exportación.

  Desde Qt 6.8, se soporta el siguiente formato: EXPORT_MACRO=macro_name[:macro_output_file[:<true|false>]]. Este formato permite especificar el nombre del archivo de cabecera que contiene la macro de exportación y controlar explícitamente si se genera.

  Nota: Si no se proporciona <fichero_salida_macro>, la opción adopta por defecto la sintaxis anterior.

• 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. El valor predeterminado es filename. Si se define la opción como pragma, se genera el pragma moderno de protección de encabezados:

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