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, it's better to utilize the Qt CMake API. For build systems other than CMake, you can adjust the commands outlined in the 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.
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 adding options to the --qtgrpc_out argument, separated 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_COMMENTScopies comments from the.protofiles into the generated code.GENERATE_PACKAGE_SUBFOLDERSuses the package name specifier from the.protofiles 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_MACROdefines the base name for the export macro used in the generated code. The final macro name is constructed asQPB_<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.
QMLenables the generation of a QML client for the gRPC service.