This directory contains CMake files that can be used to build protobuf.

You need to have CMake and Git installed on your computer before proceeding. If you don't have Abseil installed, it will be fetched from GitHub. We currently support CMake 3.22 and newer.

Most of the instructions will be given using CMake's command-line interface, but the same actions can be performed using appropriate GUI tools.

Getting Sources

You can get the latest stable source packages from the release page:

https://github.com/protocolbuffers/protobuf/releases/latest

Or you can use git to clone the protobuf git repository.

 git clone -b [release_tag] https://github.com/protocolbuffers/protobuf.git

Where [release_tag] is a git tag like v32.0-rc1 or a branch name like main if you want to get the latest code.

Basic Build

It is considered good practice not to build CMake projects in the source tree but in a separate folder. The following commands show a basic, cross-platform way to configure, build, and install protobuf.

# From the protobuf source directory
cmake -S . -B build \
  -DCMAKE_INSTALL_PREFIX=../install \
  -DCMAKE_BUILD_TYPE=Release

# Compile the code
cmake --build build --parallel 10

# Run tests
ctest --test-dir build --verbose

# Install the libraries and headers
cmake --install build

This will install the compiled libraries, headers, and protoc binary into the ../install directory, relative to the source root.

CMake Configuration Flags

The following flags can be passed to cmake during the configuration step (e.g., cmake -S . -B build -D<FLAG>=<VALUE>) to customize the build.

C++ Version

By default, CMake will use whatever C++ version is the system default. Since protobuf requires C++17 or newer, sometimes you will need to explicitly override this.

# Configure protobuf to be built with C++17
cmake . -DCMAKE_CXX_STANDARD=17

See the CMake documentation for CXX_STANDARD{.external} for all available options.

Dependency Management

Abseil and Google Test

During configuration, you can optionally specify where CMake should expect to find your Abseil, Google Test, and jsoncpp installations, if they are installed. If they aren't installed, they will be fetched from GitHub. To specify the locations, set -DCMAKE_PREFIX_PATH to the path where you installed them.

# Path to where Abseil and GTest are installed
cmake . -DCMAKE_PREFIX_PATH=/path/to/my/dependencies

If the installation of a dependency can't be found, CMake will default to downloading and building a copy from GitHub. To prevent this and make it an error condition, you can optionally set: -Dprotobuf_LOCAL_DEPENDENCIES_ONLY=ON.

Disabling Tests

To disable building the unit tests completely, set the following flag:

• -Dprotobuf_BUILD_TESTS=OFF

ZLib Support

If you want to include GzipInputStream and GzipOutputStream in libprotobuf, you need to have ZLib installed. Ensure ZLib headers and libraries are in a standard system location or a custom install prefix.

If ZLib is installed in a non-standard location, you can help CMake find it by setting:

• -DZLIB_INCLUDE_DIR=/path/to/zlib/headers
• -DZLIB_LIBRARIES=/path/to/zlib/library.lib

Build Options

DLLs vs. Static Linking

Static linking is the default. To build shared libraries (DLLs on Windows), add the following flag during configuration:

• -Dprotobuf_BUILD_SHARED_LIBS=ON

When you build your own project against protobuf, you must also define #define PROTOBUF_USE_DLLS. For more platform-specific details, see the Windows Builds section.

Compiling

The standard, cross-platform way to compile a CMake project is:

cmake --build <build_directory>

For example:

cmake --build build --parallel 10

If your generator supports multiple configurations (like Visual Studio), you must also specify which one to build:

cmake --build build --config Release

Testing

To run unit tests, first compile protobuf as described above. Then run ctest:

ctest --test-dir build --progress --output-on-failure

You can also build the check target, which will compile and run the tests:

cmake --build build --target check

To run specific tests, you need to pass arguments to the test program itself, which requires finding the test executable in your build directory.

Installing

To install protobuf to the directory specified by CMAKE_INSTALL_PREFIX during configuration, build the install target:

cmake --build <build_directory> --target install

This will create the following folders under the install location:

• bin - contains protobuf protoc compiler
• include - contains C++ headers and .proto files
• lib - contains linking libraries and CMake package configuration files.

Platform-Specific Details

Windows Builds

On Windows, you can build using Visual Studio's command-line tools or IDE.

Generators

Of most interest to Windows programmers are the following generators:

• Visual Studio: Generates a multi-configuration .sln file. Example: -G "Visual Studio 16 2019".
• Ninja: Uses the external tool Ninja to build. This is often the fastest solution.

Environment Setup

Open the appropriate Command Prompt from the Start menu (e.g., x86 Native Tools Command Prompt for VS 2019) to ensure cl.exe and other build tools are in your PATH.

DLLs vs. Static Linking on Windows

While shared libraries can be built, static linking is strongly recommended on Windows. This is due to issues with Win32‘s use of a separate heap for each DLL and binary compatibility issues between different versions of MSVC’s STL library.

If you are distributing your software, do NOT install libprotobuf.dll or libprotoc.dll to a shared location. Keep them in your application's own install directory.

Notes on Compiler Warnings

The following MSVC warnings have been disabled while building the protobuf libraries. You may need to disable them in your own project as well.

• C4065 - # switch statement contains ‘default’ but no ‘case’ labels
• C4146 - # unary minus operator applied to unsigned type
• C4244 - # ‘conversion’ conversion from ‘type1’ to ‘type2’, possible loss of data
• C4251 - # ‘identifier’ : class ‘type’ needs to have dll-interface to be used by clients of class ‘type2’
• C4267 - # ‘var’ : conversion from ‘size_t’ to ‘type’, possible loss of data
• C4305 - # ‘identifier’ : truncation from ‘type1’ to ‘type2’
• C4307 - # ‘operator’ : integral constant overflow
• C4309 - # ‘conversion’ : truncation of constant value
• C4334 - # ‘operator’ : result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?)
• C4355 - # ‘this’ : used in base member initializer list
• C4506 - # no definition for inline function ‘function’
• C4800 - # ‘type’ : forcing value to bool ‘true’ or ‘false’ (performance warning)
• C4996 - # The compiler encountered a deprecated declaration.

C4251 is particularly notable if you build protobuf as a DLL. See the old version of this document for a longer explanation if needed.

Linux Builds

Building with CMake works very similarly on Linux. You will need to have gcc or clang installed. CMake will generate Makefiles by default, but can also be configured to use Ninja.

After building, you can install the files system-wide using sudo:

 sudo cmake --install build

Or directly with Makefiles:

 cd build
 sudo make install