The qtprotobufgen Tool

The qtprotobufgen tool can be used to generate QtProtobuf 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, as shown in the following example:

 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. We use 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/imports in the specified directories.

We then 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;EXTRA_NAMESPACE=MyTopLevelNamespace"

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