- Qt 6.9
- Qt Protobuf
- The qtprotobufgen Tool
- Qt 6.9.2 Reference Documentation

Installation for Windows using vcpkg ◦ CMake Commands

# The qtprotobufgen Tool

The `qtprotobufgen` tool can be used to generate Qt Protobuf classes from a protobuf schema. The tool is provided by the CMake `Qt6::ProtobufTools` package. It works as an extension to Google's `protoc` tool.

     find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)

## Usage

Qt provides CMake functions that ease the use of the `qtprotobufgen` 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 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 protobuf schema into a Qt project.

qt_add_protobuf | Generates Qt-based C++ source code using a protobuf schema

Usually `qtprotobufgen` would be invoked through CMake using the `qt_add_protobuf` macro.

### Using qt_add_protobuf

     cmake_minimum_required(VERSION 3.16...3.22)
     project(MyThings)

     find_package(Qt6 REQUIRED COMPONENTS Protobuf)
     qt_standard_project_setup()

     qt_add_protobuf(MyMessages
         GENERATE_PACKAGE_SUBFOLDERS
         PROTO_FILES
             path/to/message.proto
             path/to/other_message.proto
         PROTO_INCLUDES
             /path/to/proto/include
     )

     qt_add_executable(MyApp main.cpp)

     target_link_libraries(MyApp PRIVATE MyMessages)

In the example above, we generate a library called `MyMessages`, which contains the message types defined in the paths passed to the `PROTO_FILES` option. The `GENERATE_PACKAGE_SUBFOLDERS` option to generate a folder structure for the generated files. And the `PROTO_INCLUDES` option tells protoc to look for dependencies or imports in the specified directories. We create a target for an executable called `MyApp`, which we link to the `MyMessages` library.

### Running manually

     protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen \
         --qtprotobuf_out="[<options>:]<output_dir>" \
         [--qtprotobuf_opt="<options>"] \
         [-I/extra/proto/include/path] \
         <protofile>.proto

The `options` argument is a semicolon-separated list of Options. It can be passed in two different ways. Either by prepending to the options to the output_dir argument, delimited by a colon. Or through a separate argument, `--qtprotobuf_opt`. You also can pass the corresponding keys as the `QT_PROTOBUF_OPTIONS` environment variable. Keys need to be presented as a semicolon-separated list:

     export QT_PROTOBUF_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_protobuf 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.