- Qt 6.5
- Qt Protobuf
- The qtgrpcgen Tool
- Qt 6.5.2 Reference Documentation

# 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.

qt_add_grpc | 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 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.