// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qt_add_protobuf.html
\ingroup cmake-commands-qtprotobuf

\title qt_add_protobuf
\target qt6_add_protobuf
\summary {Generates Qt-based C++ source code using a protobuf schema}
\preliminarycmakecommand
\cmakecommandsince 6.5

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

\badcode
    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>]
    )
\endcode

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

\section1 Arguments
\list
    \include qtprotogen-options.qdocinc 0
    \include qtprotogen-cmake-options.qdocinc 0
\endlist

\sa{The qtprotobufgen Tool}

\section1 Resolving dependencies between protobuf targets

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

The project may have two or more \c .proto files with dependencies:
\badcode
syntax = "proto3";

package test.messages;

message MyMessage {
    int32 myField = 1;
}
\endcode

\badcode
syntax = "proto3";

import "test_messages.proto";

package test.extensions;

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

\endcode

The above \c .proto files can be used to generate the standalone libraries:
\badcode
qt_add_protobuf(test_messages
    PROTO_FILES
        test_messages.proto
)
...
qt_add_protobuf(test_extensions
    PROTO_FILES
        test_extensions.proto
)
...
\endcode

Since the \c test_extensions target depends on messages from the
\c test_messages target, users need to link to such targets manually in their
\c CMake scripts:
\badcode
target_link_libraries(test_extensions PUBLIC test_messages)
\endcode

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

\section1 Example

\include qt-add-protobuf-example.qdocinc 0
*/
