| 1 |
This directory contains *CMake* files that can be used to build protobuf. |
| 2 |
|
| 3 |
You need to have [CMake](http://www.cmake.org), |
| 4 |
[Git](http://git-scm.com), and [Abseil](https://github.com/abseil/abseil-cpp) |
| 5 |
installed on your computer before proceeding. We currently support CMake 3.5 |
| 6 |
and newer on both [Windows](#windows-builds) and [Linux](#linux-builds). |
| 7 |
|
| 8 |
Most of the instructions will be given using CMake's command-line interface, but |
| 9 |
the same actions can be performed using appropriate GUI tools. |
| 10 |
|
| 11 |
# CMake Flags |
| 12 |
|
| 13 |
## C++ Version |
| 14 |
|
| 15 |
By default, CMake will use whatever C++ version is the system default. Since |
| 16 |
protobuf requires C++14 or newer, sometimes you will need to explicitly override |
| 17 |
this. For example, the following: |
| 18 |
|
| 19 |
cmake . -DCMAKE_CXX_STANDARD=14 |
| 20 |
cmake --build |
| 21 |
|
| 22 |
will build protobuf using C++14 (see [CXX_STANDARD](https://cmake.org/cmake/help/latest/prop_tgt/CXX_STANDARD.html#prop_tgt:CXX_STANDARD){.external} for all available options). |
| 23 |
|
| 24 |
# Windows Builds |
| 25 |
|
| 26 |
On Windows, you can build the project from *Command Prompt* and using an |
| 27 |
*Visual Studio* IDE. You will also need to have |
| 28 |
[Visual Studio](https://www.visualstudio.com) installed on your computer before |
| 29 |
proceeding. |
| 30 |
|
| 31 |
## Environment Setup |
| 32 |
|
| 33 |
Open the appropriate *Command Prompt* from the *Start* menu. |
| 34 |
|
| 35 |
For example *x86 Native Tools Command Prompt for VS 2019*: |
| 36 |
|
| 37 |
C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional> |
| 38 |
|
| 39 |
Change to your working directory: |
| 40 |
|
| 41 |
C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional>cd C:\Path\to |
| 42 |
C:\Path\to> |
| 43 |
|
| 44 |
Where *C:\Path\to* is path to your real working directory. |
| 45 |
|
| 46 |
Create a folder where protobuf headers/libraries/binaries will be installed after built: |
| 47 |
|
| 48 |
C:\Path\to>mkdir install |
| 49 |
|
| 50 |
If *cmake* command is not available from *Command Prompt*, add it to system *PATH* variable: |
| 51 |
|
| 52 |
C:\Path\to>set PATH=%PATH%;C:\Program Files (x86)\CMake\bin |
| 53 |
|
| 54 |
If *git* command is not available from *Command Prompt*, add it to system *PATH* variable: |
| 55 |
|
| 56 |
C:\Path\to>set PATH=%PATH%;C:\Program Files\Git\cmd |
| 57 |
|
| 58 |
Optionally, you will want to download [ninja](https://ninja-build.org/) and add it to your *PATH* variable. |
| 59 |
|
| 60 |
C:\Path\to>set PATH=%PATH%;C:\tools\ninja |
| 61 |
|
| 62 |
Good. Now you are ready to continue. |
| 63 |
|
| 64 |
## Getting Sources |
| 65 |
|
| 66 |
You can get the latest stable source packages from the release page: |
| 67 |
|
| 68 |
https://github.com/protocolbuffers/protobuf/releases/latest |
| 69 |
|
| 70 |
Or you can use git to clone from protobuf git repository. |
| 71 |
|
| 72 |
C:\Path\to> mkdir src & cd src |
| 73 |
C:\Path\to\src> git clone -b [release_tag] https://github.com/protocolbuffers/protobuf.git |
| 74 |
|
| 75 |
Where *[release_tag]* is a git tag like *v3.0.0-beta-1* or a branch name like *main* |
| 76 |
if you want to get the latest code. |
| 77 |
|
| 78 |
Go to the project folder: |
| 79 |
|
| 80 |
C:\Path\to\src> cd protobuf |
| 81 |
C:\Path\to\src\protobuf> |
| 82 |
|
| 83 |
Remember to update any submodules if you are using git clone (you can skip this |
| 84 |
step if you are using a release .tar.gz or .zip package): |
| 85 |
|
| 86 |
```console |
| 87 |
C:\Path\to\src\protobuf> git submodule update --init --recursive |
| 88 |
``` |
| 89 |
|
| 90 |
Good. Now you are ready for *CMake* configuration. |
| 91 |
|
| 92 |
## CMake Configuration |
| 93 |
|
| 94 |
*CMake* supports a lot of different |
| 95 |
[generators](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html) |
| 96 |
for various native build systems. |
| 97 |
|
| 98 |
Of most interest to Windows programmers are the following: |
| 99 |
|
| 100 |
* [Visual Studio](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) |
| 101 |
This generates a Visual Studio solution for the project. |
| 102 |
|
| 103 |
* [Ninja](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generator) |
| 104 |
This uses the external tool [Ninja](https://ninja-build.org/) to build. It is the fastest solution available. |
| 105 |
|
| 106 |
Note that as of Visual Studio 2015, Visual Studio includes |
| 107 |
[support for opening directly CMake-based projects](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio). |
| 108 |
|
| 109 |
It is considered good practice not to build CMake projects in the source tree but in a separate folder. |
| 110 |
|
| 111 |
Create a temporary *build* folder and change your working directory to it: |
| 112 |
|
| 113 |
mkdir C:\Path\to\build\protobuf |
| 114 |
cd C:\Path\to\build\protobuf |
| 115 |
C:\Path\to\build\protobuf> |
| 116 |
|
| 117 |
During configuration you will also be specifying where CMake should expect to |
| 118 |
find your Abseil installation. To do so, first set `-Dprotobuf_ABSL_PROVIDER=package` |
| 119 |
and then set `-DCMAKE_PREFIX_PATH` to the path where you installed Abseil. |
| 120 |
|
| 121 |
For example: |
| 122 |
|
| 123 |
```console |
| 124 |
C:\Path\to\build\protobuf> cmake -S. -Bcmake-out \ |
| 125 |
-DCMAKE_INSTALL_PREFIX=/tmp/protobuf \ |
| 126 |
-DCMAKE_CXX_STANDARD=14 \ |
| 127 |
-Dprotobuf_ABSL_PROVIDER=package \ |
| 128 |
-DCMAKE_PREFIX_PATH=/tmp/absl # Path to where I installed Abseil |
| 129 |
``` |
| 130 |
|
| 131 |
The *Makefile* and *Ninja* generators can build the project in only one configuration, so you need to build |
| 132 |
a separate folder for each configuration. |
| 133 |
|
| 134 |
To use *Debug* configuration using *Ninja*: |
| 135 |
|
| 136 |
C:\Path\to\build\protobuf>mkdir debug & cd debug |
| 137 |
C:\Path\to\build\protobuf\debug>cmake -G "Ninja" ^ |
| 138 |
-DCMAKE_BUILD_TYPE=Debug ^ |
| 139 |
-DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ |
| 140 |
C:\Path\to\src\protobuf |
| 141 |
|
| 142 |
It will generate *Ninja* build scripts in current directory. |
| 143 |
|
| 144 |
The *Visual Studio* generator is multi-configuration: it will generate a single *.sln* file that can be used for both *Debug* and *Release*: |
| 145 |
|
| 146 |
C:\Path\to\build\protobuf>mkdir solution & cd solution |
| 147 |
C:\Path\to\build\protobuf\solution>cmake -G "Visual Studio 16 2019" ^ |
| 148 |
-DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ |
| 149 |
C:\Path\to\src\protobuf |
| 150 |
|
| 151 |
It will generate *Visual Studio* solution file *protobuf.sln* in current directory. |
| 152 |
|
| 153 |
### Unit Tests |
| 154 |
|
| 155 |
Unit tests are being built along with the rest of protobuf. The unit tests require Google Mock (now a part of Google Test). |
| 156 |
|
| 157 |
A copy of [Google Test](https://github.com/google/googletest) is included as a Git submodule in the `third-party/googletest` folder. |
| 158 |
(You do need to initialize the Git submodules as explained above.) |
| 159 |
|
| 160 |
Alternately, you may want to use protobuf in a larger set-up, you may want to use that standard CMake approach where |
| 161 |
you build and install a shared copy of Google Test. |
| 162 |
|
| 163 |
After you've built and installed your Google Test copy, you need add the following definition to your *cmake* command line |
| 164 |
during the configuration step: `-Dprotobuf_USE_EXTERNAL_GTEST=ON`. |
| 165 |
This will cause the standard CMake `find_package(GTest REQUIRED)` to be used. |
| 166 |
|
| 167 |
[find_package](https://cmake.org/cmake/help/latest/command/find_package.html) will search in a default location, |
| 168 |
which on Windows is *C:\Program Files*. This is most likely not what you want. You will want instead to search for |
| 169 |
Google Test in your project's root directory (i.e. the same directory you've passed to `CMAKE_INSTALL_PREFIX` when |
| 170 |
building Google Test). For this, you need to set the `CMAKE_PREFIX_PATH` CMake variable. (There are other ways in CMake, |
| 171 |
see the [manual](https://cmake.org/cmake/help/latest/command/find_package.html) for details.) |
| 172 |
|
| 173 |
For example: |
| 174 |
|
| 175 |
C:\Path\to\build\protobuf>mkdir solution & cd solution |
| 176 |
C:\Path\to\build\protobuf\solution>cmake -G "Visual Studio 16 2019" ^ |
| 177 |
-DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ |
| 178 |
-DCMAKE_PREFIX_PATH=C:\Path\to\my_big_project ^ |
| 179 |
-Dprotobuf_USE_EXTERNAL_GTEST=ON ^ |
| 180 |
C:\Path\to\src\protobuf |
| 181 |
|
| 182 |
In most cases, `CMAKE_PREFIX_PATH` and `CMAKE_INSTALL_PREFIX` will point to the same directory. |
| 183 |
|
| 184 |
To disable testing completely, you need to add the following argument to you *cmake* command line: `-Dprotobuf_BUILD_TESTS=OFF`. |
| 185 |
|
| 186 |
For example: |
| 187 |
|
| 188 |
C:\Path\to\build\protobuf\solution>cmake -G "Visual Studio 16 2019" ^ |
| 189 |
-DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ |
| 190 |
-Dprotobuf_BUILD_TESTS=OFF ^ |
| 191 |
C:\Path\to\src\protobuf |
| 192 |
|
| 193 |
## Compiling |
| 194 |
|
| 195 |
The standard way to compile a *CMake* project is `cmake --build <directory>`. |
| 196 |
|
| 197 |
|
| 198 |
Note that if your generator supports multiple configurations, you will probably want to specify which one to build: |
| 199 |
|
| 200 |
cmake --build C:\Path\to\build\protobuf\solution --config Release |
| 201 |
|
| 202 |
You can also run directly the build tool you've configured: |
| 203 |
|
| 204 |
C:\Path\to\build\protobuf\debug>ninja |
| 205 |
|
| 206 |
And wait for the compilation to finish. |
| 207 |
|
| 208 |
If you prefer to use the IDE: |
| 209 |
|
| 210 |
* Open the generated protobuf.sln file in Microsoft Visual Studio. |
| 211 |
* Choose "Debug" or "Release" configuration as desired. |
| 212 |
* From the Build menu, choose "Build Solution". |
| 213 |
|
| 214 |
And wait for the compilation to finish. |
| 215 |
|
| 216 |
## Testing |
| 217 |
|
| 218 |
To run unit-tests, first you must compile protobuf as described above. |
| 219 |
Then run: |
| 220 |
|
| 221 |
C:\Path\to\protobuf\cmake\build\release>ctest --progress --output-on-failure |
| 222 |
|
| 223 |
You can also build the `check` target (not idiomatic CMake usage, though): |
| 224 |
|
| 225 |
C:\Path\to\protobuf\cmake\build\release>cmake --build . --target check |
| 226 |
|
| 227 |
or |
| 228 |
|
| 229 |
C:\Path\to\build\protobuf\release>ninja check |
| 230 |
|
| 231 |
You can also build project *check* from Visual Studio solution. |
| 232 |
Yes, it may sound strange, but it works. |
| 233 |
|
| 234 |
You should see output similar to: |
| 235 |
|
| 236 |
Running main() from gmock_main.cc |
| 237 |
[==========] Running 1546 tests from 165 test cases. |
| 238 |
|
| 239 |
... |
| 240 |
|
| 241 |
[==========] 1546 tests from 165 test cases ran. (2529 ms total) |
| 242 |
[ PASSED ] 1546 tests. |
| 243 |
|
| 244 |
To run specific tests, you need to pass some command line arguments to the test program itself: |
| 245 |
|
| 246 |
C:\Path\to\build\protobuf\release>tests.exe --gtest_filter=AnyTest* |
| 247 |
Running main() from gmock_main.cc |
| 248 |
Note: Google Test filter = AnyTest* |
| 249 |
[==========] Running 3 tests from 1 test case. |
| 250 |
[----------] Global test environment set-up. |
| 251 |
[----------] 3 tests from AnyTest |
| 252 |
[ RUN ] AnyTest.TestPackAndUnpack |
| 253 |
[ OK ] AnyTest.TestPackAndUnpack (0 ms) |
| 254 |
[ RUN ] AnyTest.TestPackAndUnpackAny |
| 255 |
[ OK ] AnyTest.TestPackAndUnpackAny (0 ms) |
| 256 |
[ RUN ] AnyTest.TestIs |
| 257 |
[ OK ] AnyTest.TestIs (0 ms) |
| 258 |
[----------] 3 tests from AnyTest (1 ms total) |
| 259 |
|
| 260 |
[----------] Global test environment tear-down |
| 261 |
[==========] 3 tests from 1 test case ran. (2 ms total) |
| 262 |
[ PASSED ] 3 tests. |
| 263 |
|
| 264 |
Note that the tests must be run from the source folder. |
| 265 |
|
| 266 |
If all tests are passed, safely continue. |
| 267 |
|
| 268 |
## Installing |
| 269 |
|
| 270 |
To install protobuf to the *install* folder you've specified in the configuration step, you need to build the `install` target: |
| 271 |
|
| 272 |
cmake --build C:\Path\to\build\protobuf\solution --config Release --target install |
| 273 |
|
| 274 |
Or if you prefer: |
| 275 |
|
| 276 |
C:\Path\to\build\protobuf\debug>ninja install |
| 277 |
|
| 278 |
You can also build project *INSTALL* from Visual Studio solution. |
| 279 |
It sounds not so strange and it works. |
| 280 |
|
| 281 |
This will create the following folders under the *install* location: |
| 282 |
* bin - that contains protobuf *protoc.exe* compiler; |
| 283 |
* include - that contains C++ headers and protobuf *.proto files; |
| 284 |
* lib - that contains linking libraries and *CMake* configuration files for *protobuf* package. |
| 285 |
|
| 286 |
Now you can if needed: |
| 287 |
* Copy the contents of the include directory to wherever you want to put headers. |
| 288 |
* Copy protoc.exe wherever you put build tools (probably somewhere in your PATH). |
| 289 |
* Copy linking libraries libprotobuf[d].lib, libprotobuf-lite[d].lib, and libprotoc[d].lib wherever you put libraries. |
| 290 |
|
| 291 |
To avoid conflicts between the MSVC debug and release runtime libraries, when |
| 292 |
compiling a debug build of your application, you may need to link against a |
| 293 |
debug build of libprotobufd.lib with "d" postfix. Similarly, release builds should link against |
| 294 |
release libprotobuf.lib library. |
| 295 |
|
| 296 |
## DLLs vs. static linking |
| 297 |
|
| 298 |
Static linking is now the default for the Protocol Buffer libraries. Due to |
| 299 |
issues with Win32's use of a separate heap for each DLL, as well as binary |
| 300 |
compatibility issues between different versions of MSVC's STL library, it is |
| 301 |
recommended that you use static linkage only. However, it is possible to |
| 302 |
build libprotobuf and libprotoc as DLLs if you really want. To do this, |
| 303 |
do the following: |
| 304 |
|
| 305 |
* Add an additional flag `-Dprotobuf_BUILD_SHARED_LIBS=ON` when invoking cmake |
| 306 |
* Follow the same steps as described in the above section. |
| 307 |
* When compiling your project, make sure to `#define PROTOBUF_USE_DLLS`. |
| 308 |
|
| 309 |
When distributing your software to end users, we strongly recommend that you |
| 310 |
do NOT install libprotobuf.dll or libprotoc.dll to any shared location. |
| 311 |
Instead, keep these libraries next to your binaries, in your application's |
| 312 |
own install directory. C++ makes it very difficult to maintain binary |
| 313 |
compatibility between releases, so it is likely that future versions of these |
| 314 |
libraries will *not* be usable as drop-in replacements. |
| 315 |
|
| 316 |
If your project is itself a DLL intended for use by third-party software, we |
| 317 |
recommend that you do NOT expose protocol buffer objects in your library's |
| 318 |
public interface, and that you statically link protocol buffers into your |
| 319 |
library. |
| 320 |
|
| 321 |
## ZLib support |
| 322 |
|
| 323 |
If you want to include GzipInputStream and GzipOutputStream |
| 324 |
(google/protobuf/io/gzip_stream.h) in libprotobuf, you will need to do a few |
| 325 |
additional steps. |
| 326 |
|
| 327 |
Obtain a copy of the zlib library. The pre-compiled DLL at zlib.net works. |
| 328 |
You need prepare it: |
| 329 |
|
| 330 |
* Make sure zlib's two headers are in your `C:\Path\to\install\include` path |
| 331 |
* Make sure zlib's linking libraries (*.lib file) is in your |
| 332 |
`C:\Path\to\install\lib` library path. |
| 333 |
|
| 334 |
You can also compile it from source by yourself. |
| 335 |
|
| 336 |
Getting sources: |
| 337 |
|
| 338 |
C:\Path\to\src>git clone -b v1.2.8 https://github.com/madler/zlib.git |
| 339 |
C:\Path\to\src>cd zlib |
| 340 |
|
| 341 |
Compiling and Installing: |
| 342 |
|
| 343 |
C:\Path\to\src\zlib>mkdir C:\Path\to\build\zlib & cd C:\Path\to\build\zlib |
| 344 |
C:\Path\to\build\zlib>mkdir release & cd release |
| 345 |
C:\Path\to\build\zlib\release>cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release ^ |
| 346 |
-DCMAKE_INSTALL_PREFIX=C:\Path\to\install C:\Path\to\src\zlib |
| 347 |
C:\Path\to\src\zlib\build\release>cmake --build . --target install |
| 348 |
|
| 349 |
You can make *debug* version or use *Visual Studio* generator also as before for the |
| 350 |
protobuf project. |
| 351 |
|
| 352 |
Now add *bin* folder from *install* to system *PATH*: |
| 353 |
|
| 354 |
C:\Path\to>set PATH=%PATH%;C:\Path\to\install\bin |
| 355 |
|
| 356 |
You need reconfigure protobuf with flag `-Dprotobuf_WITH_ZLIB=ON` when invoking cmake. |
| 357 |
|
| 358 |
Note that if you have compiled ZLIB yourself, as stated above, |
| 359 |
further disable the option `-Dprotobuf_MSVC_STATIC_RUNTIME=OFF`. |
| 360 |
|
| 361 |
If it reports NOTFOUND for zlib_include or zlib_lib, you might haven't put |
| 362 |
the headers or the .lib file in the right directory. |
| 363 |
|
| 364 |
If you already have ZLIB library and headers at some other location on your system then alternatively you can define following configuration flags to locate them: |
| 365 |
|
| 366 |
-DZLIB_INCLUDE_DIR=<path to dir containing zlib headers> |
| 367 |
-DZLIB_LIB=<path to dir containing zlib> |
| 368 |
|
| 369 |
Build and testing protobuf as usual. |
| 370 |
|
| 371 |
## Notes on Compiler Warnings |
| 372 |
|
| 373 |
The following warnings have been disabled while building the protobuf libraries |
| 374 |
and compiler. You may have to disable some of them in your own project as |
| 375 |
well, or live with them. |
| 376 |
|
| 377 |
* C4244 - Conversion from 'type1' to 'type2', possible loss of data. |
| 378 |
* C4251 - 'identifier' : class 'type' needs to have dll-interface to be used by |
| 379 |
clients of class 'type2' |
| 380 |
* C4267 - Conversion from 'size_t' to 'type', possible loss of data. |
| 381 |
* C4305 - 'identifier' : truncation from 'type1' to 'type2' |
| 382 |
* C4355 - 'this' : used in base member initializer list |
| 383 |
* C4800 - 'type' : forcing value to bool 'true' or 'false' (performance warning) |
| 384 |
* C4996 - 'function': was declared deprecated |
| 385 |
|
| 386 |
C4251 is of particular note, if you are compiling the Protocol Buffer library |
| 387 |
as a DLL (see previous section). The protocol buffer library uses templates in |
| 388 |
its public interfaces. MSVC does not provide any reasonable way to export |
| 389 |
template classes from a DLL. However, in practice, it appears that exporting |
| 390 |
templates is not necessary anyway. Since the complete definition of any |
| 391 |
template is available in the header files, anyone importing the DLL will just |
| 392 |
end up compiling instances of the templates into their own binary. The |
| 393 |
Protocol Buffer implementation does not rely on static template members being |
| 394 |
unique, so there should be no problem with this, but MSVC prints warning |
| 395 |
nevertheless. So, we disable it. Unfortunately, this warning will also be |
| 396 |
produced when compiling code which merely uses protocol buffers, meaning you |
| 397 |
may have to disable it in your code too. |
| 398 |
|
| 399 |
# Linux Builds |
| 400 |
|
| 401 |
Building with CMake works very similarly on Linux. Instead of Visual Studio, |
| 402 |
you will need to have gcc or clang installed to handle the C++ builds. CMake |
| 403 |
will generate Makefiles by default, but can also be configured to use Ninja. To |
| 404 |
build Protobuf, you will need to run (from the source directory): |
| 405 |
|
| 406 |
cmake . |
| 407 |
cmake --build . --parallel 10 |
| 408 |
|
| 409 |
Protobuf can be tested and installed with CMake: |
| 410 |
|
| 411 |
ctest --verbose |
| 412 |
sudo cmake --install . |
| 413 |
|
| 414 |
or directly with the generated Makefiles: |
| 415 |
|
| 416 |
make VERBOSE=1 test |
| 417 |
sudo make install |