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

/*!
\page qtprotobufgen-qt-tool.html
\brief An overview of the qtprotobufgen tool and how to use it.
\title The qtprotobufgen Tool
\inmodule QtProtobuf
\ingroup explanation

The \c qtprotobufgen tool can be used to generate Qt Protobuf classes from a
protobuf schema. The tool is provided by the CMake \c {Qt6::ProtobufTools}
package. It works as an extension to Google's \c protoc tool.

\badcode
    find_package(Qt6 COMPONENTS ProtobufTools REQUIRED)
\endcode

\section1 Usage

Qt provides CMake functions that ease the use of the \c qtprotobufgen tool.
When using CMake as a build tool you should prefer using the
\l{CMake Commands in Qt6 Protobuf}{Qt CMake API}.
For build systems other than CMake, adapt the commands described in
\l{Running manually}.

\note there is no explicit support for building \gRPC and Protobuf
applications using the Qt GRPC module with \e qmake.

\section2 CMake
The following CMake commands integrate a protobuf schema into a Qt project.

\target cmake-commands-qtprotobuf
\annotatedlist cmake-commands-qtprotobuf

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

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

\section2 Running manually

\badcode
    protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen \
        --qtprotobuf_out="[<options>:]<output_dir>" \
        [--qtprotobuf_opt="<options>"] \
        [-I/extra/proto/include/path] \
        <protofile>.proto
\endcode

The \c options argument is a semicolon-separated list of \l{Options}.
It can be passed in \e two different ways. Either by prepending to the options
to the output_dir argument, delimited by a colon. Or through a separate
argument, \c{--qtprotobuf_opt}.
You also can pass the corresponding keys as the \c QT_PROTOBUF_OPTIONS
environment variable. Keys need to be presented as a semicolon-separated list:
\badcode
    export QT_PROTOBUF_OPTIONS="COPY_COMMENTS;GENERATE_PACKAGE_SUBFOLDERS"
\endcode

\section2 Options
The generator supports options that can be provided to tune generation.
Options have direct aliases in the \l{qt_add_protobuf} function. The following
options are supported:

\list
    \include qtprotoccommon.qdocinc copy_comments-li
    \include qtprotoccommon.qdocinc generate_package_subfolders-li
    \include qtprotoccommon.qdocinc export_macro-cli-li
\endlist
*/
