The qtgrpcgen Tool | Qt GRPC | Qt 6.9.3
Description: An overview of the qtgrpcgen tool and how to use it.

- Qt 6.9
- Qt GRPC
- The qtgrpcgen Tool
- Qt 6.9.3 Reference Documentation

CMake Commands

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

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_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_COMMENTS` copies comments from the `.proto` files into the generated code.
- `GENERATE_PACKAGE_SUBFOLDERS` uses the package name specifier from the `.proto` files 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_MACRO` defines the base name for the export macro used in the generated code. The final macro name is constructed as `QPB_<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_GUARD` specifies the mechanism used for guarding generated header files from multiple inclusion. Possible values are `pragma`, `filename`. Defaults to `filename`. Setting the option to `pragma` generates the modern pragma header guard:

       #pragma once
       ...

  Omitting the option or setting the option to `filename` generates the `ifdef` wrapping 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.

- `QML` enables the generation of a QML client for the gRPC service.

CMake Commands