FindProtobuf — CMake 4.4.0 Documentation

# FindProtobuf

Note

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.

Added in version 3.6: Support for the `<version>` argument in `find_package(Protobuf <version>)`.

Changed in 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`

  Added in version 3.9.

  Target encapsulating the Protobuf library usage requirements, available if Protobuf library is found.

`protobuf::libprotobuf-lite`

  Added in version 3.9.

  Target encapsulating the `protobuf-lite` library usage requirements, available if Protobuf and its lite library are found.

`protobuf::libprotoc`

  Added in version 3.9.

  Target encapsulating the `protoc` library usage requirements, available if Protobuf and its `protoc` library are found.

`protobuf::protoc`

  Added in version 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`

  Added in version 3.3.

  Boolean indicating whether the (requested version of) Protobuf library was found.

`Protobuf_VERSION`

  Added in 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`

  Added in version 3.6.

  Boolean variable that enables debug messages of this module to be printed for debugging purposes.

`Protobuf_USE_STATIC_LIBS`

  Added in version 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

  Added in version 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>`

    Added in version 3.21.

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

  `PLUGIN_OPTIONS <plugin-options>`

    Added in version 3.28.

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

  `DEPENDENCIES <dependencies>...`

    Added in version 3.28.

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

    Changed in version 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>...`

    Added in version 3.28.

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

  `PROTOC_EXE <executable>`

    Added in version 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.

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

protobuf_generate_cpp

  Deprecated since version 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>`

    Added in version 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.

protobuf_generate_python

  Deprecated since version 4.1: Use `protobuf_generate()`.

  Added in version 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`

  Deprecated since version 4.1.

  A list of additional directories to search for imported `.proto` files.

`PROTOBUF_GENERATE_CPP_APPEND_PATH`

  Deprecated since version 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})