La herramienta qtgrpcgen

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

find_package(Qt6 COMPONENTS GrpcTools REQUIRED)

Uso

Qt proporciona funciones CMake que facilitan el uso de la herramienta qtgrpcgen. Cuando se utiliza CMake como herramienta de compilación, es mejor utilizar la API CMake de Qt. Para sistemas de compilación distintos de CMake, puedes ajustar manualmente los comandos descritos en la sección Ejecución de qtgrpcgen.

CMake

Los siguientes comandos de CMake integran un servicio gRPC en un proyecto Qt.

Normalmente qtgrpcgen se invocaría a través de CMake utilizando la macro qt_add_grpc, como se muestra en el siguiente ejemplo:

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

find_package(Qt6 REQUIRED COMPONENTS Protobuf Grpc)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)

qt_add_protobuf(MyApp
    PROTO_FILES
        path/to/messages.proto
)

qt_add_grpc(MyApp CLIENT
    PROTO_FILES
        path/to/service.proto
)

target_link_libraries(MyApp PRIVATE Qt6::Protobuf Qt6::Grpc)

El ejemplo anterior llama a la función CMake qt_add_grpc() para iniciar la generación de código Qt GRPC para las secciones service dentro del esquema protobuf proporcionado.

Dado que reutilizamos el objetivo ejecutable, todos los archivos generados se añadirán al objetivo, y los directorios de inclusión se actualizarán en consecuencia.

Ejecutando qtgrpcgen manualmente

protoc --plugin=protoc-gen-qtgrpc=<path/to/bin/>qtgrpcgen \
    --qtgrpc_out="[<options>:]<output_dir>" \
    [--qtgrpc_opt="<options>"] \
    [-I/extra/proto/include/path] \
    <protofile>.proto

El argumento options es una lista de opciones separadas por punto y coma. Puede pasarse añadiendo options al argumento --qtgrpc_out, separados por dos puntos, o mediante un argumento independiente, --qtgrpc_opt. También puede pasar las claves correspondientes como variable de entorno QT_GRPC_OPTIONS. Las claves deben presentarse como una lista separada por punto y coma:

export QT_GRPC_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_grpc. 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.

• QML permite generar un cliente QML para el servicio gRPC.