1 This directory contains *CMake* files that can be used to build protobuf
2 with *MSVC* on *Windows*. You can build the project from *Command Prompt*
3 and using an *Visual Studio* IDE.
4
5 You need to have [CMake](http://www.cmake.org), [Visual Studio](https://www.visualstudio.com)
6 and optionally [Git](http://git-scm.com) installed on your computer before proceeding.
7
8 Most of the instructions will be given to the *ommand Prompt*, but the same
9 actions can be performed using appropriate GUI tools.
10
11 Environment Setup
12 =================
13
14 Open the appropriate *Command Prompt* from the *Start* menu.
15
16 For example *VS2013 x64 Native Tools Command Prompt*:
17
18 C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64>
19
20 Change to your working directory:
21
22 C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64>cd C:\Path\to
23 C:\Path\to>
24
25 Where *C:\Path\to* is path to your real working directory.
26
27 Create a folder where protobuf headers/libraries/binaries will be installed after built:
28
29 C:\Path\to>mkdir install
30
31 If *cmake* command is not available from *Command Prompt*, add it to system *PATH* variable:
32
33 C:\Path\to>set PATH=%PATH%;C:\Program Files (x86)\CMake\bin
34
35 If *git* command is not available from *Command Prompt*, add it to system *PATH* variable:
36
37 C:\Path\to>set PATH=%PATH%;C:\Program Files\Git\cmd
38
39 Good. Now you are ready to continue.
40
41 Getting Sources
42 ===============
43
44 You can get the latest stable source packages from the
45 [releases](https://github.com/google/protobuf/releases) page.
46 Or you can type:
47
48 C:\Path\to> git clone -b [release_tag] https://github.com/google/protobuf.git
49
50 Where *[release_tag]* is a git tag like *v3.0.0-beta-1* or a branch name like *master*
51 if you want to get the latest code.
52
53 Go to the project folder:
54
55 C:\Path\to>cd protobuf
56 C:\Path\to\protobuf>
57
58 Protobuf unit-tests require gmock to build. If you download protobuf source code
59 from the *releases* page, the *gmock* directory should already be there. If you checkout
60 the code via `git clone`, this *gmock* directory won't exist and you will have to
61 download it manually or skip building protobuf unit-tests.
62
63 You can download gmock as follows:
64
65 C:\Path\to\protobuf>git clone -b release-1.7.0 https://github.com/google/googlemock.git gmock
66
67 Then go to *gmock* folder and download gtest:
68
69 C:\Path\to\protobuf>cd gmock
70 C:\Path\to\protobuf\gmock>git clone -b release-1.7.0 https://github.com/google/googletest.git gtest
71
72 If you absolutely don't want to build and run protobuf unit-tests, skip
73 this steps and use protobuf at your own risk.
74
75 Now go to *cmake* folder in protobuf sources:
76
77 C:\Path\to\protobuf\gmock>cd ..\cmake
78 C:\Path\to\protobuf\cmake>
79
80 Good. Now you are ready to *CMake* configuration.
81
82 CMake Configuration
83 ===================
84
85 *CMake* supports a lot of different
86 [generators](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
87 for various native build systems.
88 We are only interested in
89 [Makefile](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#makefile-generators)
90 and
91 [Visual Studio](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators)
92 generators.
93
94 We will use shadow building to separate the temporary files from the protobuf source code.
95
96 Create a temporary *build* folder and change your working directory to it:
97
98 C:\Path\to\protobuf\cmake>mkdir build & cd build
99 C:\Path\to\protobuf\cmake\build>
100
101 The *Makefile* generator can build the project in only one configuration, so you need to build
102 a separate folder for each configuration.
103
104 To start using a *Release* configuration:
105
106 C:\Path\to\protobuf\cmake\build>mkdir release & cd release
107 C:\Path\to\protobuf\cmake\build\release>cmake -G "NMake Makefiles" ^
108 -DCMAKE_BUILD_TYPE=Release ^
109 -DCMAKE_INSTALL_PREFIX=../../../../install ^
110 ../..
111
112 It will generate *nmake* *Makefile* in current directory.
113
114 To use *Debug* configuration:
115
116 C:\Path\to\protobuf\cmake\build>mkdir debug & cd debug
117 C:\Path\to\protobuf\cmake\build\debug>cmake -G "NMake Makefiles" ^
118 -DCMAKE_BUILD_TYPE=Debug ^
119 -DCMAKE_INSTALL_PREFIX=../../../../install ^
120 ../..
121
122 It will generate *nmake* *Makefile* in current directory.
123
124 To create *Visual Studio* solution file:
125
126 C:\Path\to\protobuf\cmake\build>mkdir solution & cd solution
127 C:\Path\to\protobuf\cmake\build\solution>cmake -G "Visual Studio 12 2013 Win64" ^
128 -DCMAKE_INSTALL_PREFIX=../../../../install ^
129 ../..
130
131 It will generate *Visual Studio* solution file *protobuf.sln* in current directory.
132
133 If the *gmock* directory does not exist, and you do not want to build protobuf unit tests,
134 you need to add *cmake* command argument `-Dprotobuf_BUILD_TESTS=OFF` to disable testing.
135
136 Compiling
137 =========
138
139 To compile protobuf:
140
141 C:\Path\to\protobuf\cmake\build\release>nmake
142
143 or
144
145 C:\Path\to\protobuf\cmake\build\debug>nmake
146
147 And wait for the compilation to finish.
148
149 If you prefer to use the IDE:
150
151 * Open the generated protobuf.sln file in Microsoft Visual Studio.
152 * Choose "Debug" or "Release" configuration as desired.
153 * From the Build menu, choose "Build Solution".
154
155 And wait for the compilation to finish.
156
157 Testing
158 =======
159
160 To run unit-tests, first you must compile protobuf as described above.
161 Then run:
162
163 C:\Path\to\protobuf\cmake\build\release>nmake check
164
165 or
166
167 C:\Path\to\protobuf\cmake\build\debug>nmake check
168
169 You can also build project *check* from Visual Studio solution.
170 Yes, it may sound strange, but it works.
171
172 You should see output similar to:
173
174 Running main() from gmock_main.cc
175 [==========] Running 1546 tests from 165 test cases.
176
177 ...
178
179 [==========] 1546 tests from 165 test cases ran. (2529 ms total)
180 [ PASSED ] 1546 tests.
181
182 To run specific tests:
183
184 C:\Path\to\protobuf>cmake\build\release\tests.exe --gtest_filter=AnyTest*
185 Running main() from gmock_main.cc
186 Note: Google Test filter = AnyTest*
187 [==========] Running 3 tests from 1 test case.
188 [----------] Global test environment set-up.
189 [----------] 3 tests from AnyTest
190 [ RUN ] AnyTest.TestPackAndUnpack
191 [ OK ] AnyTest.TestPackAndUnpack (0 ms)
192 [ RUN ] AnyTest.TestPackAndUnpackAny
193 [ OK ] AnyTest.TestPackAndUnpackAny (0 ms)
194 [ RUN ] AnyTest.TestIs
195 [ OK ] AnyTest.TestIs (0 ms)
196 [----------] 3 tests from AnyTest (1 ms total)
197
198 [----------] Global test environment tear-down
199 [==========] 3 tests from 1 test case ran. (2 ms total)
200 [ PASSED ] 3 tests.
201
202 Note that the tests must be run from the source folder.
203
204 If all tests are passed, safely continue.
205
206 Installing
207 ==========
208
209 To install protobuf to the specified *install* folder:
210
211 C:\Path\to\protobuf\cmake\build\release>nmake install
212
213 or
214
215 C:\Path\to\protobuf\cmake\build\debug>nmake install
216
217 You can also build project *INSTALL* from Visual Studio solution.
218 It sounds not so strange and it works.
219
220 This will create the following folders under the *install* location:
221 * bin - that contains protobuf *protoc.exe* compiler;
222 * include - that contains C++ headers and protobuf *.proto files;
223 * lib - that contains linking libraries and *CMake* configuration files for *protobuf* package.
224
225 Now you can if needed:
226 * Copy the contents of the include directory to wherever you want to put headers.
227 * Copy protoc.exe wherever you put build tools (probably somewhere in your PATH).
228 * Copy linking libraries libprotobuf[d].lib, libprotobuf-lite[d].lib, and libprotoc[d].lib wherever you put libraries.
229
230 To avoid conflicts between the MSVC debug and release runtime libraries, when
231 compiling a debug build of your application, you may need to link against a
232 debug build of libprotobufd.lib with "d" postfix. Similarly, release builds should link against
233 release libprotobuf.lib library.
234
235 DLLs vs. static linking
236 =======================
237
238 Static linking is now the default for the Protocol Buffer libraries. Due to
239 issues with Win32's use of a separate heap for each DLL, as well as binary
240 compatibility issues between different versions of MSVC's STL library, it is
241 recommended that you use static linkage only. However, it is possible to
242 build libprotobuf and libprotoc as DLLs if you really want. To do this,
243 do the following:
244
245 * Add an additional flag `-Dprotobuf_BUILD_SHARED_LIBS=ON` when invoking cmake
246 * Follow the same steps as described in the above section.
247 * When compiling your project, make sure to `#define PROTOBUF_USE_DLLS`.
248
249 When distributing your software to end users, we strongly recommend that you
250 do NOT install libprotobuf.dll or libprotoc.dll to any shared location.
251 Instead, keep these libraries next to your binaries, in your application's
252 own install directory. C++ makes it very difficult to maintain binary
253 compatibility between releases, so it is likely that future versions of these
254 libraries will *not* be usable as drop-in replacements.
255
256 If your project is itself a DLL intended for use by third-party software, we
257 recommend that you do NOT expose protocol buffer objects in your library's
258 public interface, and that you statically link protocol buffers into your
259 library.
260
261 ZLib support
262 ============
263
264 If you want to include GzipInputStream and GzipOutputStream
265 (google/protobuf/io/gzip_stream.h) in libprotobuf, you will need to do a few
266 additional steps.
267
268 Obtain a copy of the zlib library. The pre-compiled DLL at zlib.net works.
269 You need prepare it:
270
271 * Make sure zlib's two headers are in your `C:\Path\to\install\include` path
272 * Make sure zlib's linking libraries (*.lib file) is in your
273 `C:\Path\to\install\lib` library path.
274
275 You can also compile it from source by yourself.
276
277 Getting sources:
278
279 C:\Path\to>git clone -b v1.2.8 https://github.com/madler/zlib.git
280 C:\Path\to>cd zlib
281
282 Compiling and Installing:
283
284 C:\Path\to\zlib>mkdir build & cd build
285 C:\Path\to\zlib\build>mkdir release & cd release
286 C:\Path\to\zlib\build\release>cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ^
287 -DCMAKE_INSTALL_PREFIX=../../../install ../..
288 C:\Path\to\zlib\build\release>nmake & nmake install
289
290 You can make *debug* version or use *Visual Studio* generator also as before for the
291 protobuf project.
292
293 Now add *bin* folder from *install* to system *PATH*:
294
295 C:\Path\to>set PATH=%PATH%;C:\Path\to\install\bin
296
297 You need reconfigure protobuf with flag `-Dprotobuf_WITH_ZLIB=ON` when invoking cmake.
298
299 Note that if you have compiled ZLIB yourself, as stated above,
300 further disable the option `-Dprotobuf_MSVC_STATIC_RUNTIME=OFF`.
301
302 If it reports NOTFOUND for zlib_include or zlib_lib, you might haven't put
303 the headers or the .lib file in the right directory.
304
305 Build and testing protobuf as usual.
306
307 Notes on Compiler Warnings
308 ==========================
309
310 The following warnings have been disabled while building the protobuf libraries
311 and compiler. You may have to disable some of them in your own project as
312 well, or live with them.
313
314 * C4018 - 'expression' : signed/unsigned mismatch
315 * C4146 - unary minus operator applied to unsigned type, result still unsigned
316 * C4244 - Conversion from 'type1' to 'type2', possible loss of data.
317 * C4251 - 'identifier' : class 'type' needs to have dll-interface to be used by
318 clients of class 'type2'
319 * C4267 - Conversion from 'size_t' to 'type', possible loss of data.
320 * C4305 - 'identifier' : truncation from 'type1' to 'type2'
321 * C4355 - 'this' : used in base member initializer list
322 * C4800 - 'type' : forcing value to bool 'true' or 'false' (performance warning)
323 * C4996 - 'function': was declared deprecated
324
325 C4251 is of particular note, if you are compiling the Protocol Buffer library
326 as a DLL (see previous section). The protocol buffer library uses templates in
327 its public interfaces. MSVC does not provide any reasonable way to export
328 template classes from a DLL. However, in practice, it appears that exporting
329 templates is not necessary anyway. Since the complete definition of any
330 template is available in the header files, anyone importing the DLL will just
331 end up compiling instances of the templates into their own binary. The
332 Protocol Buffer implementation does not rely on static template members being
333 unique, so there should be no problem with this, but MSVC prints warning
334 nevertheless. So, we disable it. Unfortunately, this warning will also be
335 produced when compiling code which merely uses protocol buffers, meaning you
336 may have to disable it in your code too.
337