Revision control
Copy as Markdown
// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
//! [proto_files-li]
\li \c {PROTO_FILES}
specifies the list of \e {.proto} files used by the code generation
procedure.
//! [proto_files-li]
//! [proto_includes-li]
\li \c {PROTO_INCLUDES}
specifies the list of directories to be searched for protobuf dependencies.
\note The location of the \c {PROTO_FILES} is implicitly considered part of
the protobuf include path.
//! [proto_includes-li]
//! [output_directory-li]
\li \c {OUTPUT_DIRECTORY}
defines the directory where the generated files will be placed. By default,
the current build directory is used.
//! [output_directory-li]
//! [generate_package_subfolders-li]
\li \c {GENERATE_PACKAGE_SUBFOLDERS}
uses the package name specifier from the \c {.proto} files to create the
folder structure for the generated files. For example, if the package is
defined as: \c {package io.qt.test}, the generated files will be placed in
\e {OUTPUT_DIRECTORY/io/qt/test/}.
//! [generate_package_subfolders-li]
//! [copy_comments-li]
\li \c {COPY_COMMENTS}
copies comments from the \c {.proto} files into the generated code.
//! [copy_comments-li]
//! [export_macro-cmake-li]
\li \c {EXPORT_MACRO}
applies only when creating a new shared library from the \e <target>. This
option specifies the base name for the export macro used in the generated
code. The final macro name is constructed as \c
{QPB_<EXPORT_MACRO>_EXPORT}. If this option is not set, the target name is
used as \c {EXPORT_MACRO}.
Read \l {Creating Shared Libraries} for further in-depth information.
//! [export_macro-cmake-li]
//! [export_macro-cli-li]
\li \c {EXPORT_MACRO}
defines the base name for the export macro used in the generated code. The
final macro name is constructed as \c {QPB_<EXPORT_MACRO>_EXPORT}. If this
option is not set, no export macro is generated.
Since Qt 6.8, the following format is supported: \c
{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 \b {<macro_output_file>} is not provided, the option defaults to
the previous syntax.
//! [export_macro-cli-li]
//! [output_headers-li]
\li \c {OUTPUT_HEADERS}
specifies a variable that will store the list of generated headers. This list
can be useful for defining custom project install rules.
//! [output_headers-li]
//! [output_targets-li]
\li \c {OUTPUT_TARGETS}
specifies a variable that will store the list of generated targets. This
list can be useful for defining custom project install rules.
//! [output_targets-li]
//! [header_guard-li]
\li \c {HEADER_GUARD}
specifies the mechanism used for guarding generated header files from
multiple inclusion. Possible values are \c pragma, \c filename. Defaults
to \c {filename}.
Setting the option to \c pragma generates the modern pragma header guard:
\code
#pragma once
...
\endcode
Omitting the option or setting the option to \c filename generates the
\c ifdef wrapping guard, and uses the '.proto' filename as the guard infix:
\code
#ifdef MYMESSAGES_QPB_H
#define MYMESSAGES_QPB_H
...
#endif // MYMESSAGES_QPB_H
\endcode
Select the preferred guard style according to your project structure.
//! [header_guard-li]
//! [generate_non_final_messages-li]
\li \c {GENERATE_NON_FINAL_MESSAGES} (since Qt 6.11)
generates QtProtobuf message classes without the \c final specifier.
This option is provided for backwards compatibility. Since Qt 6.11,
QtProtobuf message classes are generated as \c final by default.
To extend the behavior of generated messages, prefer composition over
inheritance. This option will be removed in Qt 7.
//! [generate_non_final_messages-li]
//! [generate_non_final_properties-li]
\li \c {GENERATE_NON_FINAL_PROPERTIES} (since Qt 6.12)
generates properties of QtProtobuf message classes without the
\c FINAL specifier.
The \c FINAL specifier enables QML tooling to apply performance
optimizations and generate more efficient code.
Since Qt 6.12, QtProtobuf message properties are generated with
the \c FINAL specifier by default. This option is provided for
backwards compatibility only and will be removed in Qt 7.
For more information about the \c FINAL specifier, see
\l{The Property System}{Qt Property System}.
//! [generate_non_final_properties-li]