qt_add_protobuf

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

Note: This command is in technology preview and may change in future releases.

This command was introduced in Qt 6.5.

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

qt_add_protobuf(<target>
    PROTO_FILES <file> ...
    [COPY_COMMENTS]
    [GENERATE_PACKAGE_SUBFOLDERS]
    [EXTRA_NAMESPACE <namespace>]
    [EXPORT_MACRO <infix>]
    [PROTO_INCLUDES <path> ...]
    [OUTPUT_DIRECTORY <dir>]
    [OUTPUT_HEADERS <var>]
    [OUTPUT_TARGETS <var>]
)

The source files generated by qtprotobufgen are then added to the target. If the target already exists, the files are added to the target source list. If the target doesn't exist, it is created as a library which you must link to.

Arguments

  • 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.
  • PROTO_FILES is the list of .proto files that will be used in the generation procedure.
  • PROTO_INCLUDES is the list of directories that will be searched for dependencies.
  • OUTPUT_DIRECTORY is the directory where the generated files will be put. By default, the current directory (while evaluating the function) is used.
  • OUTPUT_HEADERS can be used to specify a variable that will hold the list of headers created by the function. This list can be useful for custom project install rules.
  • OUTPUT_TARGETS can be used to specify a variable that will hold the list of targets created by the function. This list can be useful for custom project install rules.

Resolving dependencies between protobuf targets

The qt_add_protobuf command doesn't consider the dependencies between .proto files that are used to generate code for different targets.

The project may have two or more .proto files with dependencies:

syntax = "proto3";

package test.messages;

message MyMessage {
    int32 myField = 1;
}
syntax = "proto3";

import "test_messages.proto";

package test.extensions;

message MyExtension {
    test.messages.MyMessage baseMessage = 1;
    int32 extension = 2;
}

The above .proto files can be used to generate the standalone libraries:

qt_add_protobuf(test_messages
    PROTO_FILES
        test_messages.proto
)
...
qt_add_protobuf(test_extensions
    PROTO_FILES
        test_extensions.proto
)
...

Since the test_extensions target depends on messages from the test_messages target, users need to link to such targets manually in their CMake scripts:

target_link_libraries(test_extensions PUBLIC test_messages)

Note: It's recommended to use the PUBLIC linking scope, since messages from test_messages target are referenced in header files that belong to the test_extensions target, so targets that link to test_extensions should have the test_messages target as a transitive dependency.

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.

See also The qtprotobufgen Tool.

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