Debian Codegraph @

extra/protobuf/protobuf-24.4/cmake/README.md

raw
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