FindProtobuf: Deprecate protobuf_generate_*() and update documentation

This deprecates the protobuf_generate_cpp() and protobuf_generate_python()
commands because the protobuf_generate() can work for both of these
cases and provides more options. Also, upstream Protobuf CMake-based
build system has marked these two commands as legacy and requires
setting a separate protobuf_MODULE_COMPATIBLE variable to boolean true
before calling the find_package(Protobuf).

Changes:
- Reworded and synced module documentation with other similar find
  modules.
- Imported targets moved to top.
- Moved examples to a separate section.
- Extended examples with basic usage and some quick hints how to upgrade
  deprecated commands to protobuf_generate().
- Used lowercase style of commands.
- Used "commands" instead of "functions" or "macros".
- Documented the DESCRIPTORS argument for protobuf_generate() command
  and added a note that this option is not available when Protobuf is
  found in config mode.
- Added a note about the Protobuf CMake-based build system and that
  probuf_generate*() commands might come from the upstream CMake config
  files. Mentioned also the protobuf_MODULE_COMPATIBLE variable from
  upstream CMake build system.
  See #21228.
  This fixes this issue in favor of #24321 which tracks further
  progress about Protobuf.
- Documented the missing `PROTOBUF_GENERATE_CPP_APPEND_PATH` variable.
  See #19968.

Issue: #24321
Fixes: #21228
Fixes: #19968

Help/release/3.4.rst

@@ -140,7 +140,7 @@ Modules
   (such as for related tools or data and plugin install paths).
 
 * The :module:`FindProtobuf` module gained a new
-  :command:`protobuf_generate_python` function to generate python
+  :command:`protobuf_generate_python` command to generate Python
   sources from ``.proto`` files.
 
 * The :module:`FindTIFF` module learned to search separately for

Help/release/dev/FindProtobuf.rst

@@ -3,3 +3,7 @@ FindProtobuf
 
 * The :module:`FindProtobuf` module's :command:`protobuf_generate(DEPENDENCIES)`
   command argument now accepts multiple values.
+* The :module:`FindProtobuf` module's commands :command:`protobuf_generate_cpp`
+  and :command:`protobuf_generate_python` together with their hint variables
+  ``Protobuf_IMPORT_DIRS`` and ``PROTOBUF_GENERATE_CPP_APPEND_PATH`` are now
+  deprecated in favor of :command:`protobuf_generate`.

Modules/FindProtobuf.cmake

@@ -5,204 +5,211 @@
 FindProtobuf
 ------------
 
-Locate and configure the Google Protocol Buffers library.
+.. note::
 
-.. versionadded:: 3.6
+  If the Protobuf library is built and installed using its CMake-based
-  Support for :command:`find_package` version checks.
+  build system, it provides a :ref:`package configuration file
+  <Config File Packages>` for use with the :command:`find_package` command
+  in *config mode*:
 
-.. versionchanged:: 3.6
+  .. code-block:: cmake
-  All input and output variables use the ``Protobuf_`` prefix.
-  Variables with ``PROTOBUF_`` prefix are still supported for compatibility.
 
-The following variables can be set and are optional:
+    find_package(Protobuf CONFIG)
 
-``Protobuf_SRC_ROOT_FOLDER``
+  In this case, imported targets and CMake commands such as
-  When compiling with MSVC, if this cache variable is set
+  :command:`protobuf_generate` are provided by the upstream package rather
-  the protobuf-default VS project build locations
+  than this module.  Additionally, some variables documented here are not
-  (vsprojects/Debug and vsprojects/Release
+  available in *config mode*, as imported targets are preferred.  For usage
-  or vsprojects/x64/Debug and vsprojects/x64/Release)
+  details, refer to the upstream documentation, which is the recommended
-  will be searched for libraries and binaries.
+  way to use Protobuf with CMake.
-``Protobuf_IMPORT_DIRS``
-  List of additional directories to be searched for
-  imported .proto files.
-``Protobuf_DEBUG``
-  .. versionadded:: 3.6
 
-  Show debug messages.
+  This module works only in *module mode*.
-``Protobuf_USE_STATIC_LIBS``
-  .. versionadded:: 3.9
 
-  Set to ON to force the use of the static libraries.
+This module finds the Protocol Buffers library (Protobuf) in *module mode*:
-  Default is OFF.
-
-Defines the following variables:
-
-``Protobuf_FOUND``
-  Found the Google Protocol Buffers library
-  (libprotobuf & header files)
-``Protobuf_VERSION``
-  .. versionadded:: 3.6
-
-  Version of package found.
-``Protobuf_INCLUDE_DIRS``
-  Include directories for Google Protocol Buffers
-``Protobuf_LIBRARIES``
-  The protobuf libraries
-``Protobuf_PROTOC_LIBRARIES``
-  The protoc libraries
-``Protobuf_LITE_LIBRARIES``
-  The protobuf-lite libraries
-
-.. versionadded:: 3.9
-  The following :prop_tgt:`IMPORTED` targets are also defined:
-
-``protobuf::libprotobuf``
-  The protobuf library.
-``protobuf::libprotobuf-lite``
-  The protobuf lite library.
-``protobuf::libprotoc``
-  The protoc library.
-``protobuf::protoc``
-  .. versionadded:: 3.10
-    The protoc compiler.
-
-The following cache variables are also available to set or use:
-
-``Protobuf_LIBRARY``
-  The protobuf library
-``Protobuf_PROTOC_LIBRARY``
-  The protoc library
-``Protobuf_INCLUDE_DIR``
-  The include directory for protocol buffers
-``Protobuf_PROTOC_EXECUTABLE``
-  The protoc compiler
-``Protobuf_LIBRARY_DEBUG``
-  The protobuf library (debug)
-``Protobuf_PROTOC_LIBRARY_DEBUG``
-  The protoc library (debug)
-``Protobuf_LITE_LIBRARY``
-  The protobuf lite library
-``Protobuf_LITE_LIBRARY_DEBUG``
-  The protobuf lite library (debug)
-
-Example:
 
 .. code-block:: cmake
 
-  find_package(Protobuf REQUIRED)
+  find_package(Protobuf [<version>] [...])
-  include_directories(${Protobuf_INCLUDE_DIRS})
-  include_directories(${CMAKE_CURRENT_BINARY_DIR})
-  protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
-  protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
-  protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
-  protobuf_generate_python(PROTO_PY foo.proto)
-  add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
-  target_link_libraries(bar ${Protobuf_LIBRARIES})
 
-.. note::
+Protobuf is an open-source, language-neutral, and platform-neutral mechanism
-  The ``protobuf_generate_cpp`` and ``protobuf_generate_python``
+for serializing structured data, developed by Google.  It is commonly used
-  functions and :command:`add_executable` or :command:`add_library`
+for data exchange between programs or across networks.
-  calls only work properly within the same directory.
 
-.. command:: protobuf_generate_cpp
+.. versionadded:: 3.6
+  Support for the ``<version>`` argument in
+  :command:`find_package(Protobuf \<version\>)`.
 
-  Add custom commands to process ``.proto`` files to C++:
+.. versionchanged:: 3.6
+  All input and output variables use the ``Protobuf_`` prefix.  Variables
+  with ``PROTOBUF_`` prefix are supported for backward compatibility.
 
-  .. code-block:: cmake
+Imported Targets
+^^^^^^^^^^^^^^^^
 
-    protobuf_generate_cpp (
+This module provides the following :ref:`Imported Targets`:
-      <srcs-var> <hdrs-var>
-      [DESCRIPTORS <var>]
-      [EXPORT_MACRO <macro>]
-      [<proto-file>...])
 
-  ``<srcs-var>``
+``protobuf::libprotobuf``
-    Variable to define with autogenerated source files
+  .. versionadded:: 3.9
 
-  ``<hdrs-var>``
+  Target encapsulating the Protobuf library usage requirements, available if
-    Variable to define with autogenerated header files
+  Protobuf library is found.
 
-  ``DESCRIPTORS <var>``
+``protobuf::libprotobuf-lite``
-    .. versionadded:: 3.10
+  .. versionadded:: 3.9
-      Variable to define with autogenerated descriptor files, if requested.
 
-  ``EXPORT_MACRO <macro>``
+  Target encapsulating the ``protobuf-lite`` library usage requirements,
-    is a macro which should expand to ``__declspec(dllexport)`` or
+  available if Protobuf and its lite library are found.
-    ``__declspec(dllimport)`` depending on what is being compiled.
 
-  ``<proto-file>...``
+``protobuf::libprotoc``
-    ``.proto`` files
+  .. versionadded:: 3.9
 
-.. command:: protobuf_generate_python
+  Target encapsulating the ``protoc`` library usage requirements, available
+  if Protobuf and its ``protoc`` library are found.
 
-  .. versionadded:: 3.4
+``protobuf::protoc``
+  .. versionadded:: 3.10
 
-  Add custom commands to process ``.proto`` files to Python:
+  Imported executable target encapsulating the ``protoc`` compiler usage
+  requirements, available if Protobuf and ``protoc`` are found.
 
-  .. code-block:: cmake
+Result Variables
+^^^^^^^^^^^^^^^^
 
-    protobuf_generate_python (<py-srcs-var> [<proto-file>...])
+This module defines the following variables:
 
-  ``<py-srcs-var>``
+``Protobuf_FOUND``
-    Variable to define with autogenerated Python files
+  Boolean indicating whether (the requested version of) Protobuf library is
+  found.
+``Protobuf_VERSION``
+  .. versionadded:: 3.6
 
-  ``<proto-file>...``
+  The version of Protobuf found.
-    ``.proto`` files
+``Protobuf_INCLUDE_DIRS``
+  Include directories needed to use Protobuf.
+``Protobuf_LIBRARIES``
+  Libraries needed to link against to use Protobuf.
+``Protobuf_PROTOC_LIBRARIES``
+  Libraries needed to link against to use the ``protoc`` library.
+``Protobuf_LITE_LIBRARIES``
+  Libraries needed to link against to use the ``protobuf-lite`` library.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``Protobuf_INCLUDE_DIR``
+  The include directory containing Protobuf headers.
+``Protobuf_LIBRARY``
+  The path to the ``protobuf`` library.
+``Protobuf_PROTOC_LIBRARY``
+  The path to the ``protoc`` library.
+``Protobuf_PROTOC_EXECUTABLE``
+  The path to the ``protoc`` compiler.
+``Protobuf_LIBRARY_DEBUG``
+  The path to the ``protobuf`` debug library.
+``Protobuf_PROTOC_LIBRARY_DEBUG``
+  The path to the ``protoc`` debug library.
+``Protobuf_LITE_LIBRARY``
+  The path to the ``protobuf-lite`` library.
+``Protobuf_LITE_LIBRARY_DEBUG``
+  The path to the ``protobuf-lite`` debug library.
+``Protobuf_SRC_ROOT_FOLDER``
+  When compiling with MSVC, if this cache variable is set, the
+  protobuf-default Visual Studio project build locations will be searched for
+  libraries and binaries:
+
+  * ``<Protobuf_SRC_ROOT_FOLDER>/vsprojects/{Debug,Release}``, or
+  * ``<Protobuf_SRC_ROOT_FOLDER>/vsprojects/x64/{Debug,Release}``
+
+Hints
+^^^^^
+
+This module accepts the following optional variables before calling the
+``find_package(Protobuf)``:
+
+``Protobuf_DEBUG``
+  .. versionadded:: 3.6
+
+  Boolean variable that enables debug messages of this module to be printed
+  for debugging purposes.
+
+``Protobuf_USE_STATIC_LIBS``
+  .. versionadded:: 3.9
+
+  Set to ON to force the use of the static libraries.  Default is OFF.
+
+Commands
+^^^^^^^^
+
+This module provides the following commands if Protobuf is found:
+
+Generating Source Files
+"""""""""""""""""""""""
 
 .. command:: protobuf_generate
 
   .. versionadded:: 3.13
 
-  Automatically generate source files from ``.proto`` schema files at build time:
+  Automatically generates source files from ``.proto`` schema files at build
+  time:
 
   .. code-block:: cmake
 
-    protobuf_generate (
+    protobuf_generate(
-        TARGET <target>
+      [TARGET <target>]
-        [LANGUAGE <lang>]
+      [LANGUAGE <lang>]
-        [OUT_VAR <var>]
+      [OUT_VAR <variable>]
-        [EXPORT_MACRO <macro>]
+      [EXPORT_MACRO <macro>]
-        [PROTOC_OUT_DIR <dir>]
+      [PROTOC_OUT_DIR <out-dir>]
-        [PLUGIN <plugin>]
+      [PLUGIN <plugin>]
-        [PLUGIN_OPTIONS <plugin-options>]
+      [PLUGIN_OPTIONS <plugin-options>]
-        [DEPENDENCIES <dependencies>...]
+      [DEPENDENCIES <dependencies>...]
-        [PROTOS <proto-file>...]
+      [PROTOS <proto-files>...]
-        [IMPORT_DIRS <dir>...]
+      [IMPORT_DIRS <dirs>...]
-        [GENERATE_EXTENSIONS <extension>...]
+      [APPEND_PATH]
-        [PROTOC_OPTIONS <option>...]
+      [GENERATE_EXTENSIONS <extensions>...]
-        [PROTOC_EXE <executable>]
+      [PROTOC_OPTIONS <options>...]
-        [APPEND_PATH])
+      [PROTOC_EXE <executable>]
+      [DESCRIPTORS]
+    )
 
-  ``APPEND_PATH``
+  ``TARGET <target>``
-    A flag that causes the base path of all proto schema files to be added to
+    The CMake target to which the generated files are added as sources.  This
-    ``IMPORT_DIRS``.
+    option is required when ``OUT_VAR <variable>`` is not used.
 
   ``LANGUAGE <lang>``
-    A single value: cpp or python. Determines what kind of source files are
+    A single value: ``cpp`` or ``python``.  Determines the kind of source
-    being generated. Defaults to cpp.
+    files to generate.  Defaults to ``cpp``.  For other languages, use the
+    ``GENERATE_EXTENSIONS`` option.
 
-  ``OUT_VAR <var>``
+  ``OUT_VAR <variable>``
-    Name of a CMake variable that will be filled with the paths to the generated
+    The name of a CMake variable that will be populated with the paths to
-    source files.
+    the generated source files.
 
   ``EXPORT_MACRO <macro>``
-    Name of a macro that is applied to all generated Protobuf message classes
+    The name of a preprocessor macro applied to all generated Protobuf message
-    and extern variables. It can, for example, be used to declare DLL exports.
+    classes and extern variables.  This can be used, for example, to declare
+    DLL exports.  The macro should expand to ``__declspec(dllexport)`` or
+    ``__declspec(dllimport)``, depending on what is being compiled.
 
-  ``PROTOC_OUT_DIR <dir>``
+    This option is only used when ``LANGUAGE`` is ``cpp``.
-    Output directory of generated source files. Defaults to ``CMAKE_CURRENT_BINARY_DIR``.
+
+  ``PROTOC_OUT_DIR <out-dir>``
+    The output directory for generated source files.  Defaults to:
+    :variable:`CMAKE_CURRENT_BINARY_DIR`.
 
   ``PLUGIN <plugin>``
     .. versionadded:: 3.21
 
-    An optional plugin executable. This could, for example, be the path to
+    An optional plugin executable.  This could be, for example, the path to
     ``grpc_cpp_plugin``.
 
   ``PLUGIN_OPTIONS <plugin-options>``
     .. versionadded:: 3.28
 
-    Additional options provided to the plugin, such as ``generate_mock_code=true``
+    Additional options passed to the plugin, such as ``generate_mock_code=true``
-    for the gRPC cpp plugin.
+    for the gRPC C++ plugin.
 
   ``DEPENDENCIES <dependencies>...``
     .. versionadded:: 3.28
@@ -213,50 +220,358 @@ Example:
 
     .. versionchanged:: 4.1
       This argument now accepts multiple values (``DEPENDENCIES a b c...``).
-      Previously only a single value could be specified
+      Previously, only a single value could be specified
       (``DEPENDENCIES "a;b;c;..."``).
 
-  ``TARGET <target>``
+  ``PROTOS <proto-files>...``
-    CMake target that will have the generated files added as sources.
+    A list of ``.proto`` schema files to process.  If ``<target>`` is also
+    specified, these will be combined with all ``.proto`` source files from
+    that target.
 
-  ``PROTOS <proto-file>...``
+  ``IMPORT_DIRS <dirs>...``
-    List of proto schema files. If omitted, then every source file ending in *proto* of ``TARGET`` will be used.
+    A list of one or more common parent directories for the schema files.
+    For example, if the schema file is ``proto/helloworld/helloworld.proto``
+    and the import directory is ``proto/``, then the generated files will be
+    ``<out-dir>/helloworld/helloworld.pb.h`` and
+    ``<out-dir>/helloworld/helloworld.pb.cc``.
 
-  ``IMPORT_DIRS <dir>...``
+  ``APPEND_PATH``
-    A common parent directory for the schema files. For example, if the schema file is
+    If specified, the base paths of all proto schema files are appended to
-    ``proto/helloworld/helloworld.proto`` and the import directory ``proto/`` then the
+    ``IMPORT_DIRS`` (it causes ``protoc`` to be invoked with ``-I`` argument
-    generated files are ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.h`` and
+    for each directory containing a ``.proto`` file).
-    ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.cc``.
 
-  ``GENERATE_EXTENSIONS <extension>...``
+  ``GENERATE_EXTENSIONS <extensions>...``
-    If LANGUAGE is omitted then this must be set to the extensions that protoc generates.
+    If ``LANGUAGE`` is omitted, this must be set to specify the extensions
+    generated by ``protoc``.
 
-  ``PROTOC_OPTIONS <option>...``
+  ``PROTOC_OPTIONS <options>...``
     .. versionadded:: 3.28
 
-    Additional arguments that are forwarded to protoc.
+    A list of additional command-line options passed directly to the
+    ``protoc`` compiler.
 
   ``PROTOC_EXE <executable>``
     .. versionadded:: 4.0
 
-    Command name, path, or CMake executable used to generate protobuf bindings.
+    The command-line program, path, or CMake executable used to generate
-    If omitted, ``protobuf::protoc`` is used.
+    Protobuf bindings.  If omitted, ``protobuf::protoc`` imported target is
+    used by default.
 
-  Example:
+  ``DESCRIPTORS``
+    If specified, a command-line option ``--descriptor_set_out=<proto-file>``
+    is appended to ``protoc`` compiler for each ``.proto`` source file,
+    enabling the creation of self-describing messages.  This option can only
+    be used when ``<lang>`` is ``cpp`` and Protobuf is found in *module mode*.
+
+    .. note::
+
+      This option is not available when Protobuf is found in *config mode*.
+
+Deprecated Commands
+"""""""""""""""""""
+
+The following commands are provided for backward compatibility.
+
+.. note::
+
+  The ``protobuf_generate_cpp()`` and ``protobuf_generate_python()``
+  commands work correctly only within the same directory scope, where
+  ``find_package(Protobuf ...)`` is called.
+
+.. note::
+
+  If Protobuf is found in *config mode*, the ``protobuf_generate_cpp()`` and
+  ``protobuf_generate_python()`` commands are **not available** as of
+  Protobuf version 3.0.0, unless the upstream package configuration hint
+  variable ``protobuf_MODULE_COMPATIBLE`` is set to boolean true before
+  calling ``find_package(Protobuf ...)``.
+
+.. command:: protobuf_generate_cpp
+
+  .. deprecated:: 4.1
+    Use :command:`protobuf_generate`.
+
+  Automatically generates C++ source files from ``.proto`` schema files at
+  build time:
 
   .. code-block:: cmake
 
-    find_package(gRPC CONFIG REQUIRED)
+    protobuf_generate_cpp(
-    find_package(Protobuf REQUIRED)
+      <sources-variable>
-    add_library(ProtoTest Test.proto)
+      <headers-variable>
-    target_link_libraries(ProtoTest PUBLIC gRPC::grpc++)
+      [DESCRIPTORS <variable>]
-    protobuf_generate(TARGET ProtoTest)
+      [EXPORT_MACRO <macro>]
+      <proto-files>...
+    )
+
+  ``<sources-variable>``
+    Name of the variable to define, which will contain a list of generated
+    C++ source files.
+
+  ``<headers-variable>``
+    Name of the variable to define, which will contain a list of generated
+    header files.
+
+  ``DESCRIPTORS <variable>``
+    .. versionadded:: 3.10
+
+    Name of the variable to define, which will contain a list of generated
+    descriptor files if requested.
+
+    .. note::
+      This option is not available when Protobuf is found in *config mode*.
+
+  ``EXPORT_MACRO <macro>``
+    Name of a macro that should expand to ``__declspec(dllexport)`` or
+    ``__declspec(dllimport)``, depending on what is being compiled.
+
+  ``<proto-files>...``
+    One of more ``.proto`` files to be processed.
+
+.. command:: protobuf_generate_python
+
+  .. deprecated:: 4.1
+    Use :command:`protobuf_generate`.
+
+  .. versionadded:: 3.4
+
+  Automatically generates Python source files from ``.proto`` schema files at
+  build time:
+
+  .. code-block:: cmake
+
+    protobuf_generate_python(<python-sources-variable> <proto-files>...)
+
+  ``<python-sources-variable>``
+    Name of the variable to define, which will contain a list of generated
+    Python source files.
+
+  ``<proto-files>...``
+    One or more ``.proto`` files to be processed.
+
+---------------------------------------------------------------------
+
+The ``protobuf_generate_cpp()`` and ``protobuf_generate_python()`` commands
+accept the following optional variables before being invoked:
+
+``Protobuf_IMPORT_DIRS``
+  .. deprecated:: 4.1
+
+  A list of additional directories to search for imported ``.proto`` files.
+
+``PROTOBUF_GENERATE_CPP_APPEND_PATH``
+  .. deprecated:: 4.1
+    Use :command:`protobuf_generate(APPEND_PATH)` command option.
+
+  A boolean variable that, if set to boolean true, causes ``protoc`` to be
+  invoked with ``-I`` argument for each directory containing a ``.proto``
+  file.  By default, it is set to boolean true.
+
+Examples
+^^^^^^^^
+
+Examples: Finding Protobuf
+""""""""""""""""""""""""""
+
+Finding Protobuf library:
+
+.. code-block:: cmake
+
+  find_package(Protobuf)
+
+Or, finding Protobuf and specifying a minimum required version:
+
+.. code-block:: cmake
+
+  find_package(Protobuf 30)
+
+Or, finding Protobuf and making it required (if not found, processing stops
+with an error message):
+
+.. code-block:: cmake
+
+  find_package(Protobuf REQUIRED)
+
+Example: Finding Protobuf in Config Mode
+""""""""""""""""""""""""""""""""""""""""
+
+When Protobuf library is built and installed using its CMake-based build
+system, it can be found in *config mode*:
+
+.. code-block:: cmake
+
+  find_package(Protobuf CONFIG)
+
+However, some Protobuf installations might still not provide package
+configuration file.  The following example shows, how to use the
+:variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable to find Protobuf in
+*config mode* and falling back to *module mode* if config file is not found:
+
+.. code-block:: cmake
+
+  set(CMAKE_FIND_PACKAGE_PREFER_CONFIG TRUE)
+  find_package(Protobuf)
+  unset(CMAKE_FIND_PACKAGE_PREFER_CONFIG)
+
+Example: Using Protobuf
+"""""""""""""""""""""""
+
+Finding Protobuf and linking its imported library target to a project target:
+
+.. code-block:: cmake
+
+  find_package(Protobuf)
+  target_link_libraries(example PRIVATE protobuf::libprotobuf)
+
+Example: Processing Proto Schema Files
+""""""""""""""""""""""""""""""""""""""
+
+The following example demonstrates how to process all ``*.proto`` schema
+source files added to a target into C++ source files:
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  cmake_minimum_required(VERSION 3.24)
+  project(ProtobufExample)
+
+  add_executable(example main.cxx person.proto)
+
+  find_package(Protobuf)
+
+  if(Protobuf_FOUND)
+    protobuf_generate(TARGET example)
+  endif()
+
+  target_link_libraries(example PRIVATE protobuf::libprotobuf)
+  target_include_directories(example PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
+
+.. code-block:: proto
+  :caption: ``person.proto``
+
+  syntax = "proto3";
+
+  message Person {
+    string name = 1;
+    int32 id = 2;
+  }
+
+.. code-block:: c++
+  :caption: ``main.cxx``
+
+  #include <iostream>
+  #include "person.pb.h"
+
+  int main()
+  {
+    Person person;
+    person.set_name("Alice");
+    person.set_id(123);
+
+    std::cout << "Name: " << person.name() << "\n";
+    std::cout << "ID: " << person.id() << "\n";
+
+    return 0;
+  }
+
+Example: Using Protobuf and gRPC
+""""""""""""""""""""""""""""""""
+
+The following example shows how to use Protobuf and gRPC:
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt``
+
+  find_package(Protobuf REQUIRED)
+  find_package(gRPC CONFIG REQUIRED)
+
+  add_library(ProtoExample Example.proto)
+  target_link_libraries(ProtoExample PUBLIC gRPC::grpc++)
+
+  protobuf_generate(TARGET ProtoExample)
+  protobuf_generate(
+    TARGET ProtoExample
+    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
+  )
+
+Examples: Upgrading Deprecated Commands
+"""""""""""""""""""""""""""""""""""""""
+
+The following example shows how to process ``.proto`` files to C++ code,
+using a deprecated command and its modern replacement:
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt`` with deprecated command
+
+  find_package(Protobuf)
+
+  if(Protobuf_FOUND)
+    protobuf_generate_cpp(
+      proto_sources
+      proto_headers
+      EXPORT_MACRO DLL_EXPORT
+      DESCRIPTORS proto_descriptors
+      src/protocol/Proto1.proto
+      src/protocol/Proto2.proto
+    )
+  endif()
+
+  target_sources(
+    example
+    PRIVATE ${proto_sources} ${proto_headers} ${proto_descriptors}
+  )
+  target_link_libraries(example PRIVATE protobuf::libprotobuf)
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt`` with upgraded code
+
+  find_package(Protobuf)
+
+  if(Protobuf_FOUND)
     protobuf_generate(
-        TARGET ProtoTest
+      TARGET example
-        LANGUAGE grpc
+      EXPORT_MACRO DLL_EXPORT
-        PLUGIN protoc-gen-grpc=$<TARGET_FILE:gRPC::grpc_cpp_plugin>
+      IMPORT_DIRS src/protocol
-        PLUGIN_OPTIONS generate_mock_code=true
+      DESCRIPTORS
-        GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc)
+      PROTOS
+        src/protocol/Proto1.proto
+        src/protocol/Proto2.proto
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE protobuf::libprotobuf)
+
+The following example shows how to process ``.proto`` files to Python code,
+using a deprecated command and its modern replacement:
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt`` with deprecated command
+
+  find_package(Protobuf)
+
+  if(Protobuf_FOUND)
+    protobuf_generate_python(python_sources foo.proto)
+  endif()
+
+  add_custom_target(proto_files DEPENDS ${python_sources})
+
+.. code-block:: cmake
+  :caption: ``CMakeLists.txt`` with upgraded code
+
+  find_package(Protobuf)
+
+  if(Protobuf_FOUND)
+    protobuf_generate(
+      LANGUAGE python
+      PROTOS foo.proto
+      OUT_VAR python_sources
+    )
+  endif()
+
+  add_custom_target(proto_files DEPENDS ${python_sources})
 #]=======================================================================]
 
 cmake_policy(PUSH)

Tests/FindProtobuf/Test/CMakeLists.txt

@@ -35,8 +35,8 @@ add_test(NAME test_var_protoc COMMAND test_var_protoc)
 add_test(NAME test_tgt_protoc_version COMMAND protobuf::protoc --version)
 
 set(Protobuf_IMPORT_DIRS ${Protobuf_INCLUDE_DIRS})
-PROTOBUF_GENERATE_CPP(PROTO_SRC PROTO_HEADER msgs/example.proto)
+protobuf_generate_cpp(PROTO_SRC PROTO_HEADER msgs/example.proto)
-PROTOBUF_GENERATE_CPP(DESC_PROTO_SRC DESC_PROTO_HEADER DESCRIPTORS DESC_PROTO_DESC msgs/example_desc.proto)
+protobuf_generate_cpp(DESC_PROTO_SRC DESC_PROTO_HEADER DESCRIPTORS DESC_PROTO_DESC msgs/example_desc.proto)
 add_library(msgs ${PROTO_SRC} ${PROTO_HEADER})
 target_compile_features(msgs PRIVATE cxx_std_11)