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:

 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.
• QML enables a QmlClient generation. The class is inherited from the base CLIENT class, but extends it with QML_ELEMENT macro, QML properties, and Q_INVOKABLE methods. The result of generation may be added into the QML module, that makes QmlClient available as an object from QML. See example of adding the QmlClient class into QML module below:

   qt_add_protobuf(targetname
       QML
       ...
   )
   qt_add_grpc(targetname
       QML
       ...
   )
  

  Note: for Qt 6.7 only QmlClient source code generation is supported.