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: #24321Fixes: #21228Fixes: #19968
This is a sync with the upstream `protobuf_generate()` command which has
this argument provided as a multi-value argument as of Protobuf 6.30.0
version (`cmake/protobuf-generate.cmake`).
Since commit d74210a8bd (CMP0017: Remove support for OLD behavior,
2024-11-17) we can rely on CMP0017's NEW behavior unconditionally.
Calling `include(FindPackageHandleStandardArgs)` in a builtin module
will always get the builtin `FindPackageHandleStandardArgs`.
Covers almost all blocks containing actual code, except:
* Parsed-literal blocks can't be highlighted, including many command
summaries and substitution-heavy docs like find_... commands.
This is a Sphinx limitation.
* Code with errors, like CMP0049, DEPLOYMENT_ADDITIONAL_FILES,
DEPLOYMENT_REMOTE_DIRECTORY, @PACKAGE_INIT@ substitution in the
tutorial, bracket arguments/comments in cmake-language.7 and
cmake-developer.7.
* FindQt4 module, which needs reformatting.
Append ${CMAKE_CURRENT_SOURCE_DIR} to `_protobuf_include_path` last, since
protoc will search the path in order.
Besides, we have to figure out the output directory by iterating through the
include paths and checking for valid relative paths.
This was accidentally broken by commit 31adc11030 (FindProtobuf: Add
PLUGIN_OPTIONS and PROTOC_OPTIONS to protobuf_generate, 2023-06-29,
v3.28.0-rc1~409^2~2).
Fixes: #25368
Revise the changes from commit fc7dcc6a24 (FindProtobuf: Support new
version number scheme, 2023-06-19, v3.27.0-rc3~2^2). Changing the
content of `Protobuf_VERSION` to exclude the major version of the library
might break code as it can't be used to detect breaking changes in the
library any more.
However, protoc v22 and up don't print the major version any more, so we
need to compare the against a truncated version number, too.
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] 8ec0295ad7/docs/cmake_protobuf_generate.md
Protobuf changed it's version number scheme with version 21. The first number
(usually the major version) is not synchronized between compiler and library
version, but the second and third number are. See
https://protobuf.dev/news/2022-05-06/ for more details.
Fixes: #24847
Since commit 03454b0d0d (FindProtobuf: Add missing link dependencies on
threads, 2018-10-31, v3.13.0-rc3~10^2) we add the threads library to the
list of libraries needed for Protobuf. Update the logic to do this only
when a real protobuf library is actually found.
Fixes: #21161
Define `PROTOBUF_USE_DLLS` on Windows when linking against dynamic
protobuf libraries so that we import symbols from them.
We use the condition `MSVC` to enable this because that is what
the upstream buildsystem uses.
Because cmake_parse_arguments() has been implemented as a native
command, there is no need to include(CMakeParseArguments) anymore.
Its inclusion has been removed from several CMake modules.
Tests/CMakeOnly/CMakeLists.txt has been changed to include the
*building* CMake's copy of CMakeParseArguments rather than the
*built* CMake's copy. This file included the *built* copy because
when this file was introduced, CMake could still be built with versions
that didn't supply cmake_parse_arguments(). Now, CMake requires 3.1 or
greater, where cmake_parse_arguments() existed but was still in the
form of a module, so we include it from the *building* CMake.
Protobuf headers have dependencies on threads. On UNIX platforms this
requires linking to a threads library. We've long done this in the
`Protobuf_LIBRARIES` result variable. However, the imported targets
added by commit v3.9.0-rc1~81^2~2 (FindProtobuf: add targets,
2017-05-17) and commit v3.9.0-rc1~68^2 (FindProtobuf: Rename imported
targets to match upstream names, 2017-05-22) were missing a dependency
on threads.
Add the dependency to the imported targets, and to the variables
`Protobuf_LITE_LIBRARIES` and `Protobuf_PROTOC_LIBRARIES`. While this
did not seem to matter in practice for a long time, protobuf 3.6 throws
exceptions in some cases when threads are missing.
Fixes: #18533
- The .desc files will be in the same folder as the generated .cc and .h files.
- Paths to generate .desc files are stored in a variable passed in
- This is only implemented for C++
- Remove legacy ARGS
- Add test that generates and uses C++ protobuf message
- Add test that checks that the generated .desc file can be instantiated
with DynamicMessageFactory
- Add Help rst for new feature
Reduce duplication by storing the custom command outputs in variables.
Also, since custom command outputs are automatically marked as generated
we do not need to do so explicitly.
Rename our recently added imported targets to match those provided by
the upstream's CMake-based build. That way a project using
`find_package(Protobuf)` can get the same target names no matter how
protobuf is found.
Suggested-by: Konstantin Podsvirov <konstantin@podsvirov.pro>
The change in commit v3.7.0-rc1~513^2 (FindProtobuf: fix
protobuf_generate_*() to handle proto files in subdirs, 2016-06-09)
incorrectly adds subdirectories to the path of the generated files when
`*.proto` files are passed to `protobuf_generate_*` with subdirectories.
This behavior is not correct when `PROTOBUF_GENERATE_CPP_APPEND_PATH` is
True (default behavior) as `protoc` will generate output file in the
current build directory.
