1This directory contains *CMake* files that can be used to build protobuf
2with *MSVC* on *Windows*. You can build the project from *Command Prompt*
3and using an *Visual Studio* IDE.
4
5You need to have [CMake](http://www.cmake.org), [Visual Studio](https://www.visualstudio.com)
6and optionally [Git](http://git-scm.com) installed on your computer before proceeding.
7
8Most of the instructions will be given to the *Сommand Prompt*, but the same
9actions can be performed using appropriate GUI tools.
10
11Environment Setup
12=================
13
14Open the appropriate *Command Prompt* from the *Start* menu.
15
16For example *VS2013 x64 Native Tools Command Prompt*:
17
18    C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64>
19
20Change 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
25Where *C:\Path\to* is path to your real working directory.
26
27Create a folder where protobuf headers/libraries/binaries will be installed after built:
28
29    C:\Path\to>mkdir install
30
31If *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
35If *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
39Good. Now you are ready to continue.
40
41Getting Sources
42===============
43
44You can get the latest stable source packages from the
45[releases](https://github.com/google/protobuf/releases) page.
46Or you can type:
47
48     C:\Path\to> git clone -b [release_tag] https://github.com/google/protobuf.git
49
50Where *[release_tag]* is a git tag like *v3.0.0-beta-1* or a branch name like *master*
51if you want to get the latest code.
52
53Go to the project folder:
54
55     C:\Path\to>cd protobuf
56     C:\Path\to\protobuf>
57
58Protobuf unit-tests require gmock to build. If you download protobuf source code
59from the *releases* page, the *gmock* directory should already be there. If you checkout
60the code via `git clone`, this *gmock* directory won't exist and you will have to
61download it manually or skip building protobuf unit-tests.
62
63You 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
67Then 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
72If you absolutely don't want to build and run protobuf unit-tests, skip
73this steps and use protobuf at your own risk.
74
75Now go to *cmake* folder in protobuf sources:
76
77     C:\Path\to\protobuf\gmock>cd ..\cmake
78     C:\Path\to\protobuf\cmake>
79
80Good. Now you are ready to *CMake* configuration.
81
82CMake Configuration
83===================
84
85*CMake* supports a lot of different
86[generators](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
87for various native build systems.
88We are only interested in
89[Makefile](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#makefile-generators)
90and
91[Visual Studio](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators)
92generators.
93
94We will use shadow building to separate the temporary files from the protobuf source code.
95
96Create 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
101The *Makefile* generator can build the project in only one configuration, so you need to build
102a separate folder for each configuration.
103
104To 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
112It will generate *nmake* *Makefile* in current directory.
113
114To 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
122It will generate *nmake* *Makefile* in current directory.
123
124To 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
131It will generate *Visual Studio* solution file *protobuf.sln* in current directory.
132
133If the *gmock* directory does not exist, and you do not want to build protobuf unit tests,
134you need to add *cmake* command argument `-Dprotobuf_BUILD_TESTS=OFF` to disable testing.
135
136Compiling
137=========
138
139To compile protobuf:
140
141     C:\Path\to\protobuf\cmake\build\release>nmake
142
143or
144
145     C:\Path\to\protobuf\cmake\build\debug>nmake
146
147And wait for the compilation to finish.
148
149If 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
155And wait for the compilation to finish.
156
157Testing
158=======
159
160To run unit-tests, first you must compile protobuf as described above.
161Then run:
162
163     C:\Path\to\protobuf\cmake\build\release>nmake check
164
165or
166
167     C:\Path\to\protobuf\cmake\build\debug>nmake check
168
169You can also build project *check* from Visual Studio solution.
170Yes, it may sound strange, but it works.
171
172You 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
182To 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
202Note that the tests must be run from the source folder.
203
204If all tests are passed, safely continue.
205
206Installing
207==========
208
209To install protobuf to the specified *install* folder:
210
211     C:\Path\to\protobuf\cmake\build\release>nmake install
212
213or
214
215     C:\Path\to\protobuf\cmake\build\debug>nmake install
216
217You can also build project *INSTALL* from Visual Studio solution.
218It sounds not so strange and it works.
219
220This 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
225Now 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
230To avoid conflicts between the MSVC debug and release runtime libraries, when
231compiling a debug build of your application, you may need to link against a
232debug build of libprotobufd.lib with "d" postfix.  Similarly, release builds should link against
233release libprotobuf.lib library.
234
235DLLs vs. static linking
236=======================
237
238Static linking is now the default for the Protocol Buffer libraries.  Due to
239issues with Win32's use of a separate heap for each DLL, as well as binary
240compatibility issues between different versions of MSVC's STL library, it is
241recommended that you use static linkage only.  However, it is possible to
242build libprotobuf and libprotoc as DLLs if you really want.  To do this,
243do 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
249When distributing your software to end users, we strongly recommend that you
250do NOT install libprotobuf.dll or libprotoc.dll to any shared location.
251Instead, keep these libraries next to your binaries, in your application's
252own install directory.  C++ makes it very difficult to maintain binary
253compatibility between releases, so it is likely that future versions of these
254libraries will *not* be usable as drop-in replacements.
255
256If your project is itself a DLL intended for use by third-party software, we
257recommend that you do NOT expose protocol buffer objects in your library's
258public interface, and that you statically link protocol buffers into your
259library.
260
261ZLib support
262============
263
264If you want to include GzipInputStream and GzipOutputStream
265(google/protobuf/io/gzip_stream.h) in libprotobuf, you will need to do a few
266additional steps.
267
268Obtain a copy of the zlib library.  The pre-compiled DLL at zlib.net works.
269You 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
275You can also compile it from source by yourself.
276
277Getting 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
282Compiling 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
290You can make *debug* version or use *Visual Studio* generator also as before for the
291protobuf project.
292
293Now add *bin* folder from *install* to system *PATH*:
294
295     C:\Path\to>set PATH=%PATH%;C:\Path\to\install\bin
296
297You need reconfigure protobuf with flag `-Dprotobuf_WITH_ZLIB=ON` when invoking cmake.
298
299Note that if you have compiled ZLIB yourself, as stated above,
300further disable the option `-Dprotobuf_MSVC_STATIC_RUNTIME=OFF`.
301
302If it reports NOTFOUND for zlib_include or zlib_lib, you might haven't put
303the headers or the .lib file in the right directory.
304
305Build and testing protobuf as usual.
306
307Notes on Compiler Warnings
308==========================
309
310The following warnings have been disabled while building the protobuf libraries
311and compiler.  You may have to disable some of them in your own project as
312well, 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
325C4251 is of particular note, if you are compiling the Protocol Buffer library
326as a DLL (see previous section).  The protocol buffer library uses templates in
327its public interfaces.  MSVC does not provide any reasonable way to export
328template classes from a DLL.  However, in practice, it appears that exporting
329templates is not necessary anyway.  Since the complete definition of any
330template is available in the header files, anyone importing the DLL will just
331end up compiling instances of the templates into their own binary.  The
332Protocol Buffer implementation does not rely on static template members being
333unique, so there should be no problem with this, but MSVC prints warning
334nevertheless.  So, we disable it.  Unfortunately, this warning will also be
335produced when compiling code which merely uses protocol buffers, meaning you
336may have to disable it in your code too.
337