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_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)
The example above calls the qt_add_grpc() CMake function to start Qt GRPC code generation for service sections within the provided protobuf schema.
Note: If the protobuf schema also contains message definitions, the qt_add_protobuf() CMake function should also be called to start Qt Protobuf code generation.
Since we reuse the executable target, all generated files will be appended to the target, and the include directories will be updated accordingly.
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.
HEADER_GUARDspecifies the mechanism used for guarding generated header files from multiple inclusion. Possible values arepragma,filename. Defaults tofilename. Setting the option topragmagenerates the modern pragma header guard:#pragma once ...
Omitting the option or setting the option to
filenamegenerates theifdefwrapping guard, and uses the '.proto' filename as the guard infix:#ifdef MYMESSAGES_QPB_H #define MYMESSAGES_QPB_H ... #endif // MYMESSAGES_QPB_H
Select the preferred guard style according to your project structure.
QMLenables the generation of a QML client for the gRPC service.