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 command.
qt_add_protobuf(<target>
PROTO_FILES <file> ...
[COPY_COMMENTS]
[GENERATE_PACKAGE_SUBFOLDERS]
[EXTRA_NAMESPACE <namespace>]
[EXPORT_MACRO <infix>]
[QML [QML_URI <uri>]]
[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_COMMENTScopies comments from.protofiles. If provided in the parameter list, comments related to messages and fields are copied to generated header files.GENERATE_PACKAGE_SUBFOLDERSgenerates a folder structure for the generated files matching the.protofile's package name. For example,package io.qt.test;would put the generated files intoio/qt/test/.EXTRA_NAMESPACEis 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.protofile. If this option is used, then everything will be nested inside the extra namespace.EXPORT_MACROis the base name of the symbol export macro used for the generated code. The generated macro name is constructed asQPB_<EXPORT_MACRO>_EXPORT. If the option is not set, the macro is not generated.QMLenables QProtobufMessage types in QML context by registering them as a QML module. For such purpose, the qt_add_qml_module command is called inside theqt_add_protobufcommand. Every QML module has to define aURIname. Other QML modules may use this name in import statements to import the module into a user application. Use theQML_URIoption to set theURIname. It has to be specified in dotted notation, e.g.Qt.Protobuf.Package. IfQML_URIis omitted, then the protobuf package name will be used as the moduleURI. Note that whenQMLargument is used, theqt_add_protobufcommand always creates a new QML module; therefore, it cannot be used to extend existing targets. For example, following cases are invalid:qt_add_qml_module(targetname ... ) qt_add_protobuf(targetname QML ... )qt_add_executable(targetname ... ) qt_add_protobuf(targetname QML ... )Note: If the
QML_URIis skipped, all *.proto files specified in theqt_add_protobufcommand should have the sameprotobufpackage name, since it shall be used as a defaultURIfor the resulting QML module.Note: You should avoid creating several QML modules with the same
QML_URIor proto package name, because it leads to import error in QML context.QML_URIenables QProtobufMessage types in the QML context by registering them in a QML module via the providedURIimport path. TheURIoption will be used in the line of the generatedqmldirfile, 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.PROTO_FILESis the list of.protofiles that will be used in the generation procedure.PROTO_INCLUDESis the list of directories that will be searched for dependencies.OUTPUT_DIRECTORYis the directory where the generated files will be put. By default, the current directory (while evaluating the function) is used.OUTPUT_HEADERScan 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_TARGETScan 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. 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_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, 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. 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.
See also The qtprotobufgen Tool.