docs: Add documentation to asio_grpc_protobuf_generate and README

README.md

@@ -650,3 +650,33 @@ void repeatedly_request_example(example::v1::Example::AsyncService& service, agr
 ```
 <sup><a href='/example/example-server.cpp#L130-L181' title='Snippet source file'>snippet source</a> | <a href='#snippet-repeatedly-request-spawner' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
+
+## CMake asio_grpc_protobuf_generate 
+
+In the same directory that called `find_package(asio-grpc)` a function called `asio_grpc_protobuf_generate` is made available. It can be to generate Protobuf/gRPC source files from `.proto` files:
+
+<!-- snippet: asio_grpc_protobuf_generate-target -->
+<a id='snippet-asio_grpc_protobuf_generate-target'></a>
+```cmake
+set(TARGET_GENERATED_PROTOS_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/target")
+
+asio_grpc_protobuf_generate(
+    GENERATE_GRPC
+    TARGET target-option
+    OUT_DIR "${TARGET_GENERATED_PROTOS_OUT_DIR}"
+    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/target.proto")
+
+target_include_directories(target-option PRIVATE "${TARGET_GENERATED_PROTOS_OUT_DIR}")
+```
+<sup><a href='/test/cmake/Targets.cmake#L37-L47' title='Snippet source file'>snippet source</a> | <a href='#snippet-asio_grpc_protobuf_generate-target' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+See in-code documentation for more details:
+
+<!-- snippet: asio_grpc_protobuf_generate -->
+<a id='snippet-asio_grpc_protobuf_generate'></a>
+```cmake
+function(asio_grpc_protobuf_generate)
+```
+<sup><a href='/cmake/AsioGrpcProtobufGenerator.cmake#L53-L55' title='Snippet source file'>snippet source</a> | <a href='#snippet-asio_grpc_protobuf_generate' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->

cmake/AsioGrpcProtobufGenerator.cmake

@@ -13,12 +13,51 @@
 # limitations under the License.
 
 # Adapted from the original protobuf_generate provided by protobuf-config.cmake
+#[=======================================================================[.rst:
+asio_grpc_protobuf_generate
+------------
+
+Add custom commands to process ``.proto`` files to C++::
+
+asio_grpc_protobuf_generate(PROTOS <proto_file1> [<proto_file2>...]
+                            [OUT_DIR <output_directory>]
+                            [OUT_VAR <output_variable>]
+                            [TARGET <target>]
+                            [USAGE_REQUIREMENT PRIVATE|PUBLIC|INTERFACE]
+                            [IMPORT_DIRS <directories>...]
+                            [EXTRA_ARGS <arguments>...]
+                            [GENERATE_GRPC]
+                            [GENERATE_DESCRIPTORS])
+
+``PROTOS``
+    ``.proto`` files
+``OUT_DIR``
+    Generated files output directory. Default: CMAKE_CURRENT_BINARY_DIR
+``OUT_VAR``
+    Variable to define with generated source files
+``TARGET``
+    Add generated source files to target.
+``USAGE_REQUIREMENT``
+    How to add sources to ``<target>``: ``PRIVATE``, ``PUBLIC``, ``INTERFACE``
+    Default: ``PRIVATE``
+``IMPORT_DIRS``
+    Additional import directories to be added to the protoc command line
+``EXTRA_ARGS``
+    Additional protoc command line arguments
+``GENERATE_GRPC``
+    Generate grpc files
+``GENERATE_DESCRIPTORS``
+    Generate descriptor files named <proto_file_base_name>.desc
+
+#]=======================================================================]
+# // begin-snippet: asio_grpc_protobuf_generate
 function(asio_grpc_protobuf_generate)
+    # // end-snippet: asio_grpc_protobuf_generate
     include(CMakeParseArguments)
 
     set(_asio_grpc_options GENERATE_GRPC GENERATE_DESCRIPTORS)
     set(_asio_grpc_singleargs OUT_VAR OUT_DIR TARGET USAGE_REQUIREMENT)
-    set(_asio_grpc_multiargs PROTOS IMPORT_DIRS)
+    set(_asio_grpc_multiargs PROTOS IMPORT_DIRS EXTRA_ARGS)
 
     cmake_parse_arguments(asio_grpc_protobuf_generate "${_asio_grpc_options}" "${_asio_grpc_singleargs}"
                           "${_asio_grpc_multiargs}" "${ARGN}")
@@ -91,7 +130,7 @@ function(asio_grpc_protobuf_generate)
             list(APPEND _asio_grpc_command_arguments --grpc_out "${asio_grpc_protobuf_generate_OUT_DIR}"
                  "--plugin=protoc-gen-grpc=$<TARGET_FILE:gRPC::grpc_cpp_plugin>")
         endif()
-        list(APPEND _asio_grpc_command_arguments "${_asio_grpc_abs_file}")
+        list(APPEND _asio_grpc_command_arguments ${asio_grpc_protobuf_generate_EXTRA_ARGS} "${_asio_grpc_abs_file}")
         string(REPLACE ";" " " _asio_grpc_pretty_command_arguments "${_asio_grpc_command_arguments}")
         add_custom_command(
             OUTPUT ${_asio_grpc_generated_srcs}

mdsnippets.json

@@ -6,7 +6,6 @@
     "LinkFormat": "GitHub",
     "ExcludeDirectories": [
         "build",
-        "test",
         "src"
     ],
     "MaxWidth": 150

test/cmake/CMakeLists.txt

@@ -35,85 +35,4 @@ find_package(
     NO_SYSTEM_ENVIRONMENT_PATH
     NO_CMAKE_SYSTEM_PATH)
 
-# common compile options
-add_library(compile-options INTERFACE)
-
-target_link_libraries(
-    compile-options
-    INTERFACE asio-grpc::asio-grpc
-              gRPC::grpc++
-              Boost::headers
-              Boost::coroutine
-              Boost::thread
-              ${Boost_CONTAINER_LIBRARY}
-              Boost::disable_autolinking)
-
-target_compile_definitions(
-    compile-options
-    INTERFACE $<$<CXX_COMPILER_ID:MSVC>:
-              BOOST_ASIO_HAS_DEDUCED_REQUIRE_MEMBER_TRAIT
-              BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT
-              BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT
-              BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT
-              BOOST_ASIO_HAS_DEDUCED_PREFER_MEMBER_TRAIT
-              _WIN32_WINNT=0x0A00 # Windows 10
-              WINVER=0x0A00>
-              BOOST_ASIO_NO_DEPRECATED)
-
-function(create_object_library _name)
-    add_library(${_name} OBJECT)
-
-    target_sources(${_name} PRIVATE ${ARGN})
-
-    target_link_libraries(${_name} PRIVATE compile-options)
-endfunction()
-
-# TARGET option
-create_object_library(target-option target.cpp)
-
-set(TARGET_GENERATED_PROTOS_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/target")
-
-asio_grpc_protobuf_generate(
-    GENERATE_GRPC
-    TARGET target-option
-    OUT_DIR "${TARGET_GENERATED_PROTOS_OUT_DIR}"
-    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/target.proto")
-
-target_include_directories(target-option PRIVATE "${TARGET_GENERATED_PROTOS_OUT_DIR}")
-
-# OUT_VAR option
-set(OUT_VAR_GENERATED_PROTOS_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/outVar/")
-set(OUT_VAR_GENERATED_PROTOS_OUT_DIR "${OUT_VAR_GENERATED_PROTOS_INCLUDE_DIR}/protos")
-
-asio_grpc_protobuf_generate(
-    GENERATE_GRPC
-    OUT_VAR OUT_VAR_GENERATED_SOURCES
-    OUT_DIR "${OUT_VAR_GENERATED_PROTOS_OUT_DIR}"
-    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/outVar.proto")
-
-create_object_library(out-var-option outVar.cpp ${OUT_VAR_GENERATED_SOURCES})
-
-target_include_directories(out-var-option PRIVATE "${OUT_VAR_GENERATED_PROTOS_INCLUDE_DIR}")
-
-# DESCRIPTOR option
-create_object_library(descriptor-option descriptor.cpp)
-
-set(DESCRIPTOR_GENERATED_PROTOS_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/descriptor")
-
-asio_grpc_protobuf_generate(
-    GENERATE_GRPC GENERATE_DESCRIPTORS
-    TARGET descriptor-option
-    OUT_DIR "${DESCRIPTOR_GENERATED_PROTOS_OUT_DIR}"
-    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/descriptor.proto")
-
-target_include_directories(descriptor-option PRIVATE "${DESCRIPTOR_GENERATED_PROTOS_OUT_DIR}")
-
-target_compile_definitions(descriptor-option
-                           PRIVATE "DESCRIPTOR_FILE=R\"(${DESCRIPTOR_GENERATED_PROTOS_OUT_DIR}/descriptor.desc)\"")
-
-# main
-add_executable(${PROJECT_NAME})
-
-target_sources(${PROJECT_NAME} PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/main.cpp")
-
-target_link_libraries(${PROJECT_NAME} PRIVATE target-option out-var-option descriptor-option compile-options)
+include("${CMAKE_CURRENT_LIST_DIR}/Targets.cmake")

test/cmake/Targets.cmake

@@ -0,0 +1,84 @@
+# common compile options
+add_library(compile-options INTERFACE)
+
+target_link_libraries(
+    compile-options
+    INTERFACE asio-grpc::asio-grpc
+              gRPC::grpc++
+              Boost::headers
+              Boost::coroutine
+              Boost::thread
+              ${Boost_CONTAINER_LIBRARY}
+              Boost::disable_autolinking)
+
+target_compile_definitions(
+    compile-options
+    INTERFACE $<$<CXX_COMPILER_ID:MSVC>:
+              BOOST_ASIO_HAS_DEDUCED_REQUIRE_MEMBER_TRAIT
+              BOOST_ASIO_HAS_DEDUCED_EXECUTE_MEMBER_TRAIT
+              BOOST_ASIO_HAS_DEDUCED_EQUALITY_COMPARABLE_TRAIT
+              BOOST_ASIO_HAS_DEDUCED_QUERY_MEMBER_TRAIT
+              BOOST_ASIO_HAS_DEDUCED_PREFER_MEMBER_TRAIT
+              _WIN32_WINNT=0x0A00 # Windows 10
+              WINVER=0x0A00>
+              BOOST_ASIO_NO_DEPRECATED)
+
+function(create_object_library _name)
+    add_library(${_name} OBJECT)
+
+    target_sources(${_name} PRIVATE ${ARGN})
+
+    target_link_libraries(${_name} PRIVATE compile-options)
+endfunction()
+
+# TARGET option
+create_object_library(target-option target.cpp)
+
+# // begin-snippet: asio_grpc_protobuf_generate-target
+set(TARGET_GENERATED_PROTOS_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/target")
+
+asio_grpc_protobuf_generate(
+    GENERATE_GRPC
+    TARGET target-option
+    OUT_DIR "${TARGET_GENERATED_PROTOS_OUT_DIR}"
+    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/target.proto")
+
+target_include_directories(target-option PRIVATE "${TARGET_GENERATED_PROTOS_OUT_DIR}")
+# // end-snippet: asio_grpc_protobuf_generate-target
+
+# OUT_VAR option
+set(OUT_VAR_GENERATED_PROTOS_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/outVar/")
+set(OUT_VAR_GENERATED_PROTOS_OUT_DIR "${OUT_VAR_GENERATED_PROTOS_INCLUDE_DIR}/protos")
+
+asio_grpc_protobuf_generate(
+    GENERATE_GRPC
+    OUT_VAR OUT_VAR_GENERATED_SOURCES
+    OUT_DIR "${OUT_VAR_GENERATED_PROTOS_OUT_DIR}"
+    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/outVar.proto")
+
+create_object_library(out-var-option outVar.cpp ${OUT_VAR_GENERATED_SOURCES})
+
+target_include_directories(out-var-option PRIVATE "${OUT_VAR_GENERATED_PROTOS_INCLUDE_DIR}")
+
+# DESCRIPTOR option
+create_object_library(descriptor-option descriptor.cpp)
+
+set(DESCRIPTOR_GENERATED_PROTOS_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/descriptor")
+
+asio_grpc_protobuf_generate(
+    GENERATE_GRPC GENERATE_DESCRIPTORS
+    TARGET descriptor-option
+    OUT_DIR "${DESCRIPTOR_GENERATED_PROTOS_OUT_DIR}"
+    PROTOS "${CMAKE_CURRENT_SOURCE_DIR}/descriptor.proto")
+
+target_include_directories(descriptor-option PRIVATE "${DESCRIPTOR_GENERATED_PROTOS_OUT_DIR}")
+
+target_compile_definitions(descriptor-option
+                           PRIVATE "DESCRIPTOR_FILE=R\"(${DESCRIPTOR_GENERATED_PROTOS_OUT_DIR}/descriptor.desc)\"")
+
+# main
+add_executable(${PROJECT_NAME})
+
+target_sources(${PROJECT_NAME} PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/main.cpp")
+
+target_link_libraries(${PROJECT_NAME} PRIVATE target-option out-var-option descriptor-option compile-options)