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.

CMake

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

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

// Copyright (C) 2022 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

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.

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;EXTRA_NAMESPACE=MyTopLevelNamespace"

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 .proto files. If provided in the parameter list, comments related to messages and fields are copied to generated header files.
• GENERATE_PACKAGE_SUBFOLDERS generates a folder structure for the generated files matching the .proto file's package name. For example package io.qt.test; would put the generated files into io/qt/test/.
• EXTRA_NAMESPACE is an optional namespace that will be used for the generated classes. The classes are always generated in a namespace whose name is the same as the package name specified in the .proto file. If this option is used then everything will be nested inside the extra namespace.
• EXPORT_MACRO is the base name of the symbol export macro used for the generated code. The generated macro name is constructed as QPB_<EXPORT_MACRO>_EXPORT. If the option is not set, the macro is not generated.