Merge topic 'FindProtobuf-protoc-exe-option'

53717488ea FindProtobuf: Add PROTOC_EXE option to protobuf_generate
f4dc24b527 FindProtobuf: Clarify protobuf_generate options documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !9888

Help/release/dev/FindProtobuf-protoc-exe-option.rst

@@ -0,0 +1,5 @@
+FindProtobuf-protoc-exe-option
+------------------------------
+
+* The :module:`FindProtobuf` module :command:`protobuf_generate` command
+  gained a ``PROTOC_EXE`` option to specify a custom ``protoc`` executable.

Modules/FindProtobuf.cmake

@@ -108,20 +108,27 @@ Example:
 
   Add custom commands to process ``.proto`` files to C++::
 
-    protobuf_generate_cpp (<SRCS> <HDRS>
-        [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
+    protobuf_generate_cpp (
+      <srcs-var> <hdrs-var>
+      [DESCRIPTORS <var>]
+      [EXPORT_MACRO <macro>]
+      [<proto-file>...])
 
-  ``SRCS``
+  ``<srcs-var>``
     Variable to define with autogenerated source files
-  ``HDRS``
+
+  ``<hdrs-var>``
     Variable to define with autogenerated header files
-  ``DESCRIPTORS``
+
+  ``DESCRIPTORS <var>``
     .. versionadded:: 3.10
       Variable to define with autogenerated descriptor files, if requested.
-  ``EXPORT_MACRO``
+
+  ``EXPORT_MACRO <macro>``
     is a macro which should expand to ``__declspec(dllexport)`` or
     ``__declspec(dllimport)`` depending on what is being compiled.
-  ``ARGN``
+
+  ``<proto-file>...``
     ``.proto`` files
 
 .. command:: protobuf_generate_python
@@ -130,11 +137,12 @@ Example:
 
   Add custom commands to process ``.proto`` files to Python::
 
-    protobuf_generate_python (<PY> [<ARGN>...])
+    protobuf_generate_python (<py-srcs-var> [<proto-file>...])
 
-  ``PY``
+  ``<py-srcs-var>``
     Variable to define with autogenerated Python files
-  ``ARGN``
+
+  ``<proto-file>...``
     ``.proto`` files
 
 .. command:: protobuf_generate
@@ -146,63 +154,82 @@ Example:
     protobuf_generate (
         TARGET <target>
         [LANGUAGE <lang>]
-        [OUT_VAR <out_var>]
+        [OUT_VAR <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>]
+        [PLUGIN_OPTIONS <plugin-options>]
+        [DEPENDENCIES <dependencies>]
+        [PROTOS <proto-file>...]
+        [IMPORT_DIRS <dir>...]
+        [GENERATE_EXTENSIONS <extension>...]
+        [PROTOC_OPTIONS <option>...]
+        [PROTOC_EXE <executable>]
         [APPEND_PATH])
 
   ``APPEND_PATH``
     A flag that causes the base path of all proto schema files to be added to
     ``IMPORT_DIRS``.
-  ``LANGUAGE``
+
+  ``LANGUAGE <lang>``
     A single value: cpp or python. Determines what kind of source files are
     being generated. Defaults to cpp.
-  ``OUT_VAR``
+
+  ``OUT_VAR <var>``
     Name of a CMake variable that will be filled with the paths to the generated
     source files.
-  ``EXPORT_MACRO``
+
+  ``EXPORT_MACRO <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``
+
+  ``PROTOC_OUT_DIR <dir>``
     Output directory of generated source files. Defaults to ``CMAKE_CURRENT_BINARY_DIR``.
-  ``PLUGIN``
+
+  ``PLUGIN <plugin>``
     .. versionadded:: 3.21
 
     An optional plugin executable. This could, for example, be the path to
     ``grpc_cpp_plugin``.
-  ``PLUGIN_OPTIONS``
+
+  ``PLUGIN_OPTIONS <plugin-options>``
     .. versionadded:: 3.28
 
     Additional options provided to the plugin, such as ``generate_mock_code=true``
     for the gRPC cpp plugin.
-  ``DEPENDENCIES``
+
+  ``DEPENDENCIES <dependencies>``
     .. versionadded:: 3.28
 
     Arguments forwarded to the ``DEPENDS`` of the underlying ``add_custom_command``
     invocation.
-  ``TARGET``
+
+  ``TARGET <target>``
     CMake target that will have the generated files added as sources.
-  ``PROTOS``
+
+  ``PROTOS <proto-file>...``
     List of proto schema files. If omitted, then every source file ending in *proto* of ``TARGET`` will be used.
-  ``IMPORT_DIRS``
+
+  ``IMPORT_DIRS <dir>...``
     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``
+
+  ``GENERATE_EXTENSIONS <extension>...``
     If LANGUAGE is omitted then this must be set to the extensions that protoc generates.
-  ``PROTOC_OPTIONS``
+
+  ``PROTOC_OPTIONS <option>...``
     .. versionadded:: 3.28
 
     Additional arguments that are forwarded to protoc.
 
+  ``PROTOC_EXE <executable>``
+    .. versionadded:: 3.32
+
+    Command name, path, or CMake executable used to generate protobuf bindings.
+    If omitted, ``protobuf::protoc`` is used.
+
   Example::
 
     find_package(gRPC CONFIG REQUIRED)
@@ -223,7 +250,7 @@ cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n>
 
 function(protobuf_generate)
   set(_options APPEND_PATH DESCRIPTORS)
-  set(_singleargs LANGUAGE OUT_VAR EXPORT_MACRO PROTOC_OUT_DIR PLUGIN PLUGIN_OPTIONS DEPENDENCIES)
+  set(_singleargs LANGUAGE OUT_VAR EXPORT_MACRO PROTOC_OUT_DIR PLUGIN PLUGIN_OPTIONS DEPENDENCIES PROTOC_EXE)
   if(COMMAND target_sources)
     list(APPEND _singleargs TARGET)
   endif()
@@ -292,10 +319,14 @@ function(protobuf_generate)
     return()
   endif()
 
-  if(NOT TARGET protobuf::protoc)
-    message(SEND_ERROR "protoc executable not found. "
-            "Please define the Protobuf_PROTOC_EXECUTABLE variable or ensure that protoc is in CMake's search path.")
-    return()
+  if(NOT protobuf_generate_PROTOC_EXE)
+    if(NOT TARGET protobuf::protoc)
+      message(SEND_ERROR "protoc executable not found. "
+        "Please define the Protobuf_PROTOC_EXECUTABLE variable, or pass PROTOC_EXE to protobuf_generate, or ensure that protoc is in CMake's search path.")
+      return()
+    endif()
+    # Default to using the CMake executable
+    set(protobuf_generate_PROTOC_EXE protobuf::protoc)
   endif()
 
   if(protobuf_generate_APPEND_PATH)
@@ -368,7 +399,7 @@ function(protobuf_generate)
 
     add_custom_command(
       OUTPUT ${_generated_srcs}
-      COMMAND protobuf::protoc
+      COMMAND ${protobuf_generate_PROTOC_EXE}
       ARGS ${protobuf_generate_PROTOC_OPTIONS} --${protobuf_generate_LANGUAGE}_out ${_plugin_options}:${protobuf_generate_PROTOC_OUT_DIR} ${_plugin} ${_dll_desc_out} ${_protobuf_include_path} ${_abs_file}
       DEPENDS ${_abs_file} protobuf::protoc ${protobuf_generate_DEPENDENCIES}
       COMMENT ${_comment}

Tests/FindProtobuf/CMakeLists.txt

@@ -9,3 +9,4 @@ add_test(NAME FindProtobuf.Test COMMAND
   "-DCMake_TEST_FindProtobuf_gRPC=${CMake_TEST_FindProtobuf_gRPC}"
   --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
   )
+set_property(TEST FindProtobuf.Test PROPERTY FAIL_REGULAR_EXPRESSION PROTOC_EXE)

Tests/FindProtobuf/Test/CMakeLists.txt

@@ -70,7 +70,7 @@ if(CMake_TEST_FindProtobuf_gRPC)
   # NOTE: with IMPORT_DIRS msgs/, generated files will be placed under ${CMAKE_CURRENT_BINARY_DIR}/grpc/
   target_include_directories(msgs_grpc_IMPORT_DIRS PUBLIC ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/grpc/)
   target_link_libraries(msgs_grpc_IMPORT_DIRS PUBLIC ${Protobuf_LIBRARIES})
-  protobuf_generate(TARGET msgs_grpc_IMPORT_DIRS LANGUAGE cpp IMPORT_DIRS msgs/)
+  protobuf_generate(TARGET msgs_grpc_IMPORT_DIRS LANGUAGE cpp IMPORT_DIRS msgs/ PROTOC_EXE ${Protobuf_PROTOC_EXECUTABLE})
   protobuf_generate(TARGET msgs_grpc_IMPORT_DIRS LANGUAGE grpc IMPORT_DIRS msgs/ GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc PLUGIN "protoc-gen-grpc=${gRPC_CPP_PLUGIN}")
   add_executable(test_generate_grpc_IMPORT_DIRS main-generate-grpc.cxx)
   target_link_libraries(test_generate_grpc_IMPORT_DIRS PRIVATE msgs_grpc_IMPORT_DIRS)