The qtgrpcgen Tool

The qtgrpcgen tool can be used to generate Qt GRPC service classes from a protobuf schema. The tool is provided by the CMake Qt6::GrpcTools package. It works as an extension to Google's protoc tool.

find_package(Qt6 COMPONENTS GrpcTools REQUIRED)

Usage

Qt provides CMake functions that ease the use of the qtgrpcgen tool. When using CMake as a build tool you should prefer using the Qt CMake API. For build systems other than CMake, adapt the commands described in Running qtgrpcgen manually.

Note: there is no explicit support for building gRPC and Protobuf applications using the Qt GRPC module with qmake.

CMake

The following CMake commands integrate a gRPC service into a Qt project.

qt_add_grpc

Generates Qt-based C++ services using a protobuf schema

Usually qtgrpcgen would be invoked through CMake using the qt_add_grpc macro, as shown in the following example:

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

find_package(Qt6 REQUIRED COMPONENTS Protobuf Grpc)
qt_standard_project_setup()

qt_add_protobuf(MyProtoMessageLib
    PROTO_FILES
        path/to/helloworld.proto
    PROTO_INCLUDES
        path/to/proto/include
)

qt_add_grpc(MyGrpcClient CLIENT
    PROTO_FILES
        path/to/helloworld.proto
    PROTO_INCLUDES
        path/to/proto/include
)

qt_add_executable(MyApp main.cpp)

target_link_libraries(MyApp PRIVATE MyGrpcClient MyProtoMessageLib Qt6::Protobuf)

The example above calls the qt_add_grpc() CMake function to generate a library called MyGrpcClient.

Note: if the .proto file API contains messages, then the qt_add_protobuf() CMake function should be called to generate protobuf message classes for the project.

Finally, the example creates a target for an executable called MyApp which links to the MyGrpcClient and MyProtoMessageLib libraries.

Running qtgrpcgen manually

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

The options argument is a semicolon-separated list of Options. It can be passed by prepending the options to the output_dir argument, delimited by a colon, or through a separate argument, --qtgrpc_opt. You also can pass the corresponding keys as the QT_GRPC_OPTIONS environment variable. Keys must be presented as a semicolon-separated list:

export QT_GRPC_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"

Options

The generator supports options that can be provided to tune generation. Options have direct aliases in the qt_add_grpc function. The following options are supported:

  • COPY_COMMENTS copies comments from the .proto files into the generated code.
  • GENERATE_PACKAGE_SUBFOLDERS uses the package name specifier from the .proto files to create the folder structure for the generated files. For example, if the package is defined as: package io.qt.test, the generated files will be placed in OUTPUT_DIRECTORY/io/qt/test/.
  • EXPORT_MACRO defines the base name for the export macro used in the generated code. The final macro name is constructed as QPB_<EXPORT_MACRO>_EXPORT. If this option is not set, no export macro is generated.

    Since Qt 6.8, the following format is supported: EXPORT_MACRO=macro_name[:macro_output_file[:<true|false>]]. This format allows you to specify the name of the header file containing the export macro and explicitly control whether it is generated.

    Note: If <macro_output_file> is not provided, the option defaults to the previous syntax.

  • QML enables the generation of a QML client for the gRPC service.

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