mirror of
https://github.com/Kitware/CMake.git
synced 2025-05-07 22:06:42 +08:00
Merge topic 'patch-FindProtobuf'
1bdb0ee1b8 FindProtobuf: Deprecate protobuf_generate_*() and update documentation Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !10742
This commit is contained in:
Brad King
Kitware Robot
commit
015cada32d
@ -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
|
||||
|
||||
@ -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`.
|
||||
|
||||
@ -5,204 +5,211 @@
|
||||
FindProtobuf
|
||||
------------
|
||||
|
||||
Locate and configure the Google Protocol Buffers library.
|
||||
.. note::
|
||||
|
||||
.. versionadded:: 3.6
|
||||
Support for :command:`find_package` version checks.
|
||||
If the Protobuf library is built and installed using its CMake-based
|
||||
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
|
||||
All input and output variables use the ``Protobuf_`` prefix.
|
||||
Variables with ``PROTOBUF_`` prefix are still supported for compatibility.
|
||||
.. code-block:: cmake
|
||||
|
||||
The following variables can be set and are optional:
|
||||
find_package(Protobuf CONFIG)
|
||||
|
||||
``Protobuf_SRC_ROOT_FOLDER``
|
||||
When compiling with MSVC, if this cache variable is set
|
||||
the protobuf-default VS project build locations
|
||||
(vsprojects/Debug and vsprojects/Release
|
||||
or vsprojects/x64/Debug and vsprojects/x64/Release)
|
||||
will be searched for libraries and binaries.
|
||||
``Protobuf_IMPORT_DIRS``
|
||||
List of additional directories to be searched for
|
||||
imported .proto files.
|
||||
``Protobuf_DEBUG``
|
||||
.. versionadded:: 3.6
|
||||
In this case, imported targets and CMake commands such as
|
||||
:command:`protobuf_generate` are provided by the upstream package rather
|
||||
than this module. Additionally, some variables documented here are not
|
||||
available in *config mode*, as imported targets are preferred. For usage
|
||||
details, refer to the upstream documentation, which is the recommended
|
||||
way to use Protobuf with CMake.
|
||||
|
||||
Show debug messages.
|
||||
``Protobuf_USE_STATIC_LIBS``
|
||||
.. versionadded:: 3.9
|
||||
This module works only in *module mode*.
|
||||
|
||||
Set to ON to force the use of the static libraries.
|
||||
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:
|
||||
This module finds the Protocol Buffers library (Protobuf) in *module mode*:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_package(Protobuf REQUIRED)
|
||||
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})
|
||||
find_package(Protobuf [<version>] [...])
|
||||
|
||||
.. note::
|
||||
The ``protobuf_generate_cpp`` and ``protobuf_generate_python``
|
||||
functions and :command:`add_executable` or :command:`add_library`
|
||||
calls only work properly within the same directory.
|
||||
Protobuf is an open-source, language-neutral, and platform-neutral mechanism
|
||||
for serializing structured data, developed by Google. It is commonly used
|
||||
for data exchange between programs or across networks.
|
||||
|
||||
.. 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 (
|
||||
<srcs-var> <hdrs-var>
|
||||
[DESCRIPTORS <var>]
|
||||
[EXPORT_MACRO <macro>]
|
||||
[<proto-file>...])
|
||||
This module provides the following :ref:`Imported Targets`:
|
||||
|
||||
``<srcs-var>``
|
||||
Variable to define with autogenerated source files
|
||||
``protobuf::libprotobuf``
|
||||
.. versionadded:: 3.9
|
||||
|
||||
``<hdrs-var>``
|
||||
Variable to define with autogenerated header files
|
||||
Target encapsulating the Protobuf library usage requirements, available if
|
||||
Protobuf library is found.
|
||||
|
||||
``DESCRIPTORS <var>``
|
||||
.. versionadded:: 3.10
|
||||
Variable to define with autogenerated descriptor files, if requested.
|
||||
``protobuf::libprotobuf-lite``
|
||||
.. versionadded:: 3.9
|
||||
|
||||
``EXPORT_MACRO <macro>``
|
||||
is a macro which should expand to ``__declspec(dllexport)`` or
|
||||
``__declspec(dllimport)`` depending on what is being compiled.
|
||||
Target encapsulating the ``protobuf-lite`` library usage requirements,
|
||||
available if Protobuf and its lite library are found.
|
||||
|
||||
``<proto-file>...``
|
||||
``.proto`` files
|
||||
``protobuf::libprotoc``
|
||||
.. 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>``
|
||||
Variable to define with autogenerated Python files
|
||||
``Protobuf_FOUND``
|
||||
Boolean indicating whether (the requested version of) Protobuf library is
|
||||
found.
|
||||
``Protobuf_VERSION``
|
||||
.. versionadded:: 3.6
|
||||
|
||||
``<proto-file>...``
|
||||
``.proto`` files
|
||||
The version of Protobuf found.
|
||||
``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 (
|
||||
TARGET <target>
|
||||
[LANGUAGE <lang>]
|
||||
[OUT_VAR <var>]
|
||||
[EXPORT_MACRO <macro>]
|
||||
[PROTOC_OUT_DIR <dir>]
|
||||
[PLUGIN <plugin>]
|
||||
[PLUGIN_OPTIONS <plugin-options>]
|
||||
[DEPENDENCIES <dependencies>...]
|
||||
[PROTOS <proto-file>...]
|
||||
[IMPORT_DIRS <dir>...]
|
||||
[GENERATE_EXTENSIONS <extension>...]
|
||||
[PROTOC_OPTIONS <option>...]
|
||||
[PROTOC_EXE <executable>]
|
||||
[APPEND_PATH])
|
||||
protobuf_generate(
|
||||
[TARGET <target>]
|
||||
[LANGUAGE <lang>]
|
||||
[OUT_VAR <variable>]
|
||||
[EXPORT_MACRO <macro>]
|
||||
[PROTOC_OUT_DIR <out-dir>]
|
||||
[PLUGIN <plugin>]
|
||||
[PLUGIN_OPTIONS <plugin-options>]
|
||||
[DEPENDENCIES <dependencies>...]
|
||||
[PROTOS <proto-files>...]
|
||||
[IMPORT_DIRS <dirs>...]
|
||||
[APPEND_PATH]
|
||||
[GENERATE_EXTENSIONS <extensions>...]
|
||||
[PROTOC_OPTIONS <options>...]
|
||||
[PROTOC_EXE <executable>]
|
||||
[DESCRIPTORS]
|
||||
)
|
||||
|
||||
``APPEND_PATH``
|
||||
A flag that causes the base path of all proto schema files to be added to
|
||||
``IMPORT_DIRS``.
|
||||
``TARGET <target>``
|
||||
The CMake target to which the generated files are added as sources. This
|
||||
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
|
||||
being generated. Defaults to cpp.
|
||||
A single value: ``cpp`` or ``python``. Determines the kind of source
|
||||
files to generate. Defaults to ``cpp``. For other languages, use the
|
||||
``GENERATE_EXTENSIONS`` option.
|
||||
|
||||
``OUT_VAR <var>``
|
||||
Name of a CMake variable that will be filled with the paths to the generated
|
||||
source files.
|
||||
``OUT_VAR <variable>``
|
||||
The name of a CMake variable that will be populated with the paths to
|
||||
the generated source files.
|
||||
|
||||
``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.
|
||||
The name of a preprocessor macro applied to all generated Protobuf message
|
||||
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>``
|
||||
Output directory of generated source files. Defaults to ``CMAKE_CURRENT_BINARY_DIR``.
|
||||
This option is only used when ``LANGUAGE`` is ``cpp``.
|
||||
|
||||
``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``
|
||||
for the gRPC cpp plugin.
|
||||
Additional options passed to the plugin, such as ``generate_mock_code=true``
|
||||
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>``
|
||||
CMake target that will have the generated files added as sources.
|
||||
``PROTOS <proto-files>...``
|
||||
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>...``
|
||||
List of proto schema files. If omitted, then every source file ending in *proto* of ``TARGET`` will be used.
|
||||
``IMPORT_DIRS <dirs>...``
|
||||
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>...``
|
||||
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``.
|
||||
``APPEND_PATH``
|
||||
If specified, the base paths of all proto schema files are appended to
|
||||
``IMPORT_DIRS`` (it causes ``protoc`` to be invoked with ``-I`` argument
|
||||
for each directory containing a ``.proto`` file).
|
||||
|
||||
``GENERATE_EXTENSIONS <extension>...``
|
||||
If LANGUAGE is omitted then this must be set to the extensions that protoc generates.
|
||||
``GENERATE_EXTENSIONS <extensions>...``
|
||||
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.
|
||||
If omitted, ``protobuf::protoc`` is used.
|
||||
The command-line program, path, or CMake executable used to generate
|
||||
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)
|
||||
find_package(Protobuf REQUIRED)
|
||||
add_library(ProtoTest Test.proto)
|
||||
target_link_libraries(ProtoTest PUBLIC gRPC::grpc++)
|
||||
protobuf_generate(TARGET ProtoTest)
|
||||
protobuf_generate_cpp(
|
||||
<sources-variable>
|
||||
<headers-variable>
|
||||
[DESCRIPTORS <variable>]
|
||||
[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
|
||||
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)
|
||||
TARGET example
|
||||
EXPORT_MACRO DLL_EXPORT
|
||||
IMPORT_DIRS src/protocol
|
||||
DESCRIPTORS
|
||||
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)
|
||||
|
||||
@ -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(DESC_PROTO_SRC DESC_PROTO_HEADER DESCRIPTORS DESC_PROTO_DESC msgs/example_desc.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)
|
||||
add_library(msgs ${PROTO_SRC} ${PROTO_HEADER})
|
||||
target_compile_features(msgs PRIVATE cxx_std_11)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user