FindProtobuf¶

Примечание

If the Protobuf library is built and installed using its CMake-based build system, it provides a package configuration file for use with the find_package() command in config mode:

find_package(Protobuf CONFIG)

In this case, imported targets and CMake commands such as 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.

This module works only in module mode.

This module finds the Protocol Buffers library (Protobuf) in module mode:

find_package(Protobuf [<version>] [...])

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.

Добавлено в версии 3.6: Support for the <version> argument in find_package(Protobuf <version>).

Изменено в версии 3.6: All input and output variables use the Protobuf_ prefix. Variables with PROTOBUF_ prefix are supported for backward compatibility.

Imported Targets¶

This module provides the following Imported Targets:

protobuf::libprotobuf: Добавлено в версии 3.9.

Target encapsulating the Protobuf library usage requirements, available if Protobuf library is found.
protobuf::libprotobuf-lite: Добавлено в версии 3.9.

Target encapsulating the protobuf-lite library usage requirements, available if Protobuf and its lite library are found.
protobuf::libprotoc: Добавлено в версии 3.9.

Target encapsulating the protoc library usage requirements, available if Protobuf and its protoc library are found.
protobuf::protoc: Добавлено в версии 3.10.

Imported executable target encapsulating the protoc compiler usage requirements, available if Protobuf and protoc are found.

Result Variables¶

This module defines the following variables:

Protobuf_FOUND: Boolean indicating whether (the requested version of) Protobuf library is found.
Protobuf_VERSION: Добавлено в версии 3.6.

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: Добавлено в версии 3.6.

Boolean variable that enables debug messages of this module to be printed for debugging purposes.
Protobuf_USE_STATIC_LIBS: Добавлено в версии 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¶

protobuf_generate¶

Добавлено в версии 3.13.

Automatically generates source files from .proto schema files at build time:

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]
)

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 the kind of source files to generate. Defaults to cpp. For other languages, use the GENERATE_EXTENSIONS option.

OUT_VAR <variable>

The name of a CMake variable that will be populated with the paths to the generated source files.

EXPORT_MACRO <macro>

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.

This option is only used when LANGUAGE is cpp.

PROTOC_OUT_DIR <out-dir>

The output directory for generated source files. Defaults to: CMAKE_CURRENT_BINARY_DIR.

PLUGIN <plugin>

Добавлено в версии 3.21.

An optional plugin executable. This could be, for example, the path to grpc_cpp_plugin.

PLUGIN_OPTIONS <plugin-options>

Добавлено в версии 3.28.

Additional options passed to the plugin, such as generate_mock_code=true for the gRPC C++ plugin.

DEPENDENCIES <dependencies>...

Добавлено в версии 3.28.

Dependencies on which the generation of files depends on. These are forwarded to the underlying add_custom_command(DEPENDS) invocation.

Изменено в версии 4.1: This argument now accepts multiple values (DEPENDENCIES a b c...). Previously, only a single value could be specified (DEPENDENCIES "a;b;c;...").

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.

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.

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 <extensions>...

If LANGUAGE is omitted, this must be set to specify the extensions generated by protoc.

PROTOC_OPTIONS <options>...

Добавлено в версии 3.28.

A list of additional command-line options passed directly to the protoc compiler.

PROTOC_EXE <executable>

Добавлено в версии 4.0.

The command-line program, path, or CMake executable used to generate Protobuf bindings. If omitted, protobuf::protoc imported target is used by default.

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.

Примечание

This option is not available when Protobuf is found in config mode.

Deprecated Commands¶

The following commands are provided for backward compatibility.

Примечание

The protobuf_generate_cpp() and protobuf_generate_python() commands work correctly only within the same directory scope, where find_package(Protobuf ...) is called.

Примечание

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 ...).

protobuf_generate_cpp¶

Устарело, начиная с версии 4.1: Use protobuf_generate().

Automatically generates C++ source files from .proto schema files at build time:

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>: Добавлено в версии 3.10.

Name of the variable to define, which will contain a list of generated descriptor files if requested.

Примечание

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.

protobuf_generate_python¶

Устарело, начиная с версии 4.1: Use protobuf_generate().

Добавлено в версии 3.4.

Automatically generates Python source files from .proto schema files at build time:

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: Устарело, начиная с версии 4.1.

A list of additional directories to search for imported .proto files.
PROTOBUF_GENERATE_CPP_APPEND_PATH: Устарело, начиная с версии 4.1: Use 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:

find_package(Protobuf)

Or, finding Protobuf and specifying a minimum required version:

find_package(Protobuf 30)

Or, finding Protobuf and making it required (if not found, processing stops with an error message):

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:

find_package(Protobuf CONFIG)

However, some Protobuf installations might still not provide package configuration file. The following example shows, how to use the CMAKE_FIND_PACKAGE_PREFER_CONFIG variable to find Protobuf in config mode and falling back to module mode if config file is not found:

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:

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:

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})

person.proto¶

syntax = "proto3";

message Person {
  string name = 1;
  int32 id = 2;
}

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:

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:

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)

CMakeLists.txt with upgraded code¶

find_package(Protobuf)

if(Protobuf_FOUND)
  protobuf_generate(
    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:

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})

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})

FindProtobuf¶

Imported Targets¶

Result Variables¶

Cache Variables¶

Hints¶

Commands¶

Generating Source Files¶

Deprecated Commands¶

Examples¶

Examples: Finding Protobuf¶

Example: Finding Protobuf in Config Mode¶

Example: Using Protobuf¶

Example: Processing Proto Schema Files¶

Example: Using Protobuf and gRPC¶

Examples: Upgrading Deprecated Commands¶

Оглавление

Предыдущий раздел

Следующий раздел

Эта страница