Contents

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, as shown in the following examples:

 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.

QML extended protobuf example

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

 find_package(Qt6 REQUIRED COMPONENTS Protobuf Quick)
 qt_standard_project_setup()

 qt_add_protobuf(MyMessagesPlugin
     QML
     QML_URI my.messages.module.uri
     PROTO_FILES
         path/to/message.proto
         path/to/other_message.proto
     PROTO_INCLUDES
         /path/to/proto/include
 )

 qt_add_protobuf(MyApp
     QML
     PROTO_FILES
         path/to/internal_message.proto
     PROTO_INCLUDES
         /path/to/proto/include
 )

 qt_add_qml_module(MyApp
     URI example.uri
     VERSION 1.0
     QML_FILES qml/main.qml
 )

 qt_add_executable(MyApp main.cpp)
 target_link_libraries(MyApp PRIVATE Quick)

In the QML extended example above, by the first qt_add_protobuf call, we generate a QML module called MyMessagesPlugin, which contains the message types defined in the paths passed to the PROTO_FILES option. We use the QML option, that enables proto message types registration in the QML context. The registered types will be available in QML by importing a path that is set by the QML_URI. By second qt_add_protobuf call we add auto-generated code into the existing MyApp QML module. The QML_URI is not required in such cases. Finally, we create a target for an executable called MyApp, which has a QML module for the graphical part and loads MyMessagesPlugin into the main.qml file via the my.messages.module.uri import.

Installing standalone Qt Protobuf library

The qt_add_protobuf command also produces lists of artifacts for further installation. You can read these artifacts by specifying OUTPUT_HEADERS, and OUTPUT_TARGETS arguments as follows:

 qt_add_protobuf(MyProtoLib
     PROTO_FILES
         mylib.proto
     OUTPUT_HEADERS
         public_headers
     OUTPUT_TARGETS
         generated_targets
 )

The command stores the list of the header files and targets produced by the qt_add_protobuf command to the public_headers and generated_targets variables accordingly.

Use the standard CMake install command to install the artifacts and generate the config files for your library:

 include(GNUInstallDirs)
 set_target_properties(MyProtoLib PROPERTIES
     PUBLIC_HEADER
         "${public_headers}"
     INTERFACE_INCLUDE_DIRECTORIES
         "$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}>"
 )
 install(TARGETS ${generated_targets} EXPORT MyProtoLibTargets
     PUBLIC_HEADER
         DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
 )
 install(EXPORT MyProtoLibTargets NAMESPACE MyProtoLib:: DESTINATION lib/cmake/MyProtoLib)

Then use the generated MyProtoLibTargets config in the package config file. You can read more about the package creation process in the official CMake documentation.

After installation the library is available as the standalone CMake package:

 find_package(Qt6 COMPONENTS Protobuf)
 find_package(MyProtoLib CONFIG)

 add_executable(MyApp main.cpp)
 target_link_libraries(MyApp PRIVATE MyProtoLib::MyProtoLib Qt6::Protobuf)

Note: qt_add_protobuf doesn't implicitly add Qt Protobuf module as the transitive dependency, neither for the MyProtoLib target nor for the MyProtoLib CMake package. Therefore, the Qt Protobuf module lookup and the explicit linking of MyApp to Qt6::Protobuf are mandatory.

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.
  • QML_URI enables QProtobufMessage types in the QML context by registering them in a QML module via the provided URI import path. The URI option will be used in the line of the generated qmldir file, and also used to form the target path by replacing dots with forward slashes.

    Note: Read Identified Modules for further in-depth discussion of the URI.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.