FindProtobuf: Add documentation for protobuf_generate()

Note, the argument `DESCRIPTORS` is not documented as upstream doesn't
provide this argument and code might break when switching to upstream
later.

Instead of the argument `DESCRIPTORS`
`PROTOC_OPTIONS "--descriptor_set_out=NAME.desc"` can be used.

Argument description has been copied from [1].

Fixes: #23037

[1] https://github.com/protocolbuffers/protobuf/blob/8ec0295ad7fc83d20609fcdf4830e3e3fddf2912/docs/cmake_protobuf_generate.md

1 files changed, 80 insertions, 0 deletions

diff --git a/Modules/FindProtobuf.cmake b/Modules/FindProtobuf.cmake
index 649e571..3455412 100644
--- a/Modules/FindProtobuf.cmake
+++ b/Modules/FindProtobuf.cmake
@@ -136,6 +136,86 @@ Example:
     Variable to define with autogenerated Python files
   ``ARGN``
     ``.proto`` files
+
+.. command:: protobuf_generate
+
+  .. versionadded:: 3.13
+
+  Automatically generate source files from ``.proto`` schema files at build time::
+
+    protobuf_generate (
+        TARGET <target>
+        [LANGUAGE <lang>]
+        [OUT_VAR <out_var>]
+        [EXPORT_MACRO <macro>]
+        [PROTOC_OUT_DIR <dir>]
+        [PLUGIN <plugin>]
+        [PLUGIN_OPTIONS <plugin_options>]
+        [DEPENDENCIES <depends]
+        [PROTOS <protobuf_files>]
+        [IMPORT_DIRS <dirs>]
+        [GENERATE_EXTENSIONS <extensions>]
+        [PROTOC_OPTIONS <protoc_options>]
+        [APPEND_PATH])
+
+  ``APPEND_PATH``
+    A flag that causes the base path of all proto schema files to be added to
+    ``IMPORT_DIRS``.
+  ``LANGUAGE``
+    A single value: cpp or python. Determines what kind of source files are
+    being generated. Defaults to cpp.
+  ``OUT_VAR``
+    Name of a CMake variable that will be filled with the paths to the generated
+    source files.
+  ``EXPORT_MACRO``
+    Name of a macro that is applied to all generated Protobuf message classes
+    and extern variables. It can, for example, be used to declare DLL exports.
+  ``PROTOC_OUT_DIR``
+    Output directory of generated source files. Defaults to ``CMAKE_CURRENT_BINARY_DIR``.
+  ``PLUGIN``
+    .. versionadded:: 3.21
+
+    An optional plugin executable. This could, for example, be the path to
+    ``grpc_cpp_plugin``.
+  ``PLUGIN_OPTIONS``
+    .. versionadded:: 3.28
+
+    Additional options provided to the plugin, such as ``generate_mock_code=true``
+    for the gRPC cpp plugin.
+  ``DEPENDENCIES``
+    .. versionadded:: 3.28
+
+    Arguments forwarded to the ``DEPENDS`` of the underlying ``add_custom_command``
+    invocation.
+  ``TARGET``
+    CMake target that will have the generated files added as sources.
+  ``PROTOS``
+    List of proto schema files. If omitted, then every source file ending in *proto* of ``TARGET`` will be used.
+  ``IMPORT_DIRS``
+    A common parent directory for the schema files. For example, if the schema file is
+    ``proto/helloworld/helloworld.proto`` and the import directory ``proto/`` then the
+    generated files are ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.h`` and
+    ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.cc``.
+  ``GENERATE_EXTENSIONS``
+    If LANGUAGE is omitted then this must be set to the extensions that protoc generates.
+  ``PROTOC_OPTIONS``
+    .. versionadded:: 3.28
+
+    Additional arguments that are forwarded to protoc.
+
+  Example::
+
+    find_package(gRPC CONFIG REQUIRED)
+    find_package(Protobuf REQUIRED)
+    add_library(ProtoTest Test.proto)
+    target_link_libraries(ProtoTest PUBLIC gRPC::grpc++)
+    protobuf_generate(TARGET ProtoTest)
+    protobuf_generate(
+        TARGET ProtoTest
+        LANGUAGE grpc
+        PLUGIN protoc-gen-grpc=$<TARGET_FILE:gRPC::grpc_cpp_plugin>
+        PLUGIN_OPTIONS generate_mock_code=true
+        GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc)
 #]=======================================================================]
 
 function(protobuf_generate)