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.
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.
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.
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.
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.
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
.
To disable building the unit tests completely, set the following flag:
-Dprotobuf_BUILD_TESTS=OFF
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
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.
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
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.
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
compilerinclude
- contains C++ headers and .proto
fileslib
- contains linking libraries and CMake package configuration files.On Windows, you can build using Visual Studio's command-line tools or IDE.
Of most interest to Windows programmers are the following generators:
.sln
file. Example: -G "Visual Studio 16 2019"
.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
.
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.
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’ labelsC4146
- # unary minus operator applied to unsigned typeC4244
- # ‘conversion’ conversion from ‘type1’ to ‘type2’, possible loss of dataC4251
- # ‘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 dataC4305
- # ‘identifier’ : truncation from ‘type1’ to ‘type2’C4307
- # ‘operator’ : integral constant overflowC4309
- # ‘conversion’ : truncation of constant valueC4334
- # ‘operator’ : result of 32-bit shift implicitly converted to 64 bits (was 64-bit shift intended?)C4355
- # ‘this’ : used in base member initializer listC4506
- # 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.
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