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.
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;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 examplepackage io.qt.test;
would put the generated files intoio/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 asQPB_<EXPORT_MACRO>_EXPORT
. If the option is not set, the macro is not generated.