En esta página

La herramienta qtgrpcgen

La herramienta qtgrpcgen se puede utilizar para generar clases de servicio de « Qt GRPC » a partir de un esquema protobuf. La herramienta la proporciona el paquete CMake Qt6::GrpcTools. Funciona como una extensión de la herramienta de Google protoc.

find_package(Qt6 COMPONENTS GrpcTools REQUIRED)

Uso

Qt proporciona funciones de CMake que facilitan el uso de la herramienta qtgrpcgen. Cuando se utiliza CMake como herramienta de compilación, es mejor recurrir a la API de CMake de Qt. Para sistemas de compilación distintos de CMake, puedes adaptar los comandos descritos en la sección «Ejecución manual de qtgrpcgen».

Nota: No existe soporte explícito para la compilación de gRPC™ y de aplicaciones Protobuf utilizando el módulo Qt GRPC con qmake.

CMake

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

qt_add_grpc

Genera servicios en C++ basados en Qt utilizando un esquema protobuf

Normalmente, qtgrpcgen se invoca a través de CMake utilizando la macro qt_add_grpc, tal y 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 de CMake qt_add_grpc() para iniciar la generación de código Qt GRPC para las secciones « service » del esquema protobuf proporcionado.

Nota: Si el esquema protobuf también contiene definiciones de ` message `, también se debe llamar a la función de CMake ` qt_add_protobuf() ` para iniciar la generación de código ` Qt Protobuf `.

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.

Ejecución manual de qtgrpcgen

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. Se puede pasar añadiendo ` options ` al argumento ` --qtgrpc_out `, separado por dos puntos, o mediante un argumento independiente, ` --qtgrpc_opt`. También se pueden 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 » al código generado.
  • GENERATE_PACKAGE_SUBFOLDERS utiliza el especificador del nombre del 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 establece esta opción, no se genera ninguna macro de exportación.

    Desde Qt 6.8, se admite 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 o no.

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

  • 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. Al establecer 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 según la estructura de tu proyecto.

  • QML permite la generación de un cliente QML para el servicio gRPC.

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