336 lines
12 KiB
Markdown
336 lines
12 KiB
Markdown
This directory contains *CMake* files that can be used to build protobuf
|
||
with *MSVC* on *Windows*. You can build the project from *Command Prompt*
|
||
and using an *Visual Studio* IDE.
|
||
|
||
You need to have [CMake](http://www.cmake.org), [Visual Studio](https://www.visualstudio.com)
|
||
and optionally [Git](http://git-scm.com) installed on your computer before proceeding.
|
||
|
||
Most of the instructions will be given to the *Сommand Prompt*, but the same
|
||
actions can be performed using appropriate GUI tools.
|
||
|
||
Environment Setup
|
||
=================
|
||
|
||
Open the appropriate *Command Prompt* from the *Start* menu.
|
||
|
||
For example *VS2013 x64 Native Tools Command Prompt*:
|
||
|
||
C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64>
|
||
|
||
Change to your working directory:
|
||
|
||
C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64>cd C:\Path\to
|
||
C:\Path\to>
|
||
|
||
Where *C:\Path\to* is path to your real working directory.
|
||
|
||
Create a folder where protobuf headers/libraries/binaries will be installed after built:
|
||
|
||
C:\Path\to>mkdir install
|
||
|
||
If *cmake* command is not available from *Command Prompt*, add it to system *PATH* variable:
|
||
|
||
C:\Path\to>set PATH=%PATH%;C:\Program Files (x86)\CMake\bin
|
||
|
||
If *git* command is not available from *Command Prompt*, add it to system *PATH* variable:
|
||
|
||
C:\Path\to>set PATH=%PATH%;C:\Program Files\Git\cmd
|
||
|
||
Good. Now you are ready to continue.
|
||
|
||
Getting Sources
|
||
===============
|
||
|
||
You can get the latest stable source packages from the
|
||
[releases](https://github.com/google/protobuf/releases) page.
|
||
Or you can type:
|
||
|
||
C:\Path\to> git clone -b [release_tag] https://github.com/google/protobuf.git
|
||
|
||
Where *[release_tag]* is a git tag like *v3.0.0-beta-1* or a branch name like *master*
|
||
if you want to get the latest code.
|
||
|
||
Go to the project folder:
|
||
|
||
C:\Path\to>cd protobuf
|
||
C:\Path\to\protobuf>
|
||
|
||
Protobuf unit-tests require gmock to build. If you download protobuf source code
|
||
from the *releases* page, the *gmock* directory should already be there. If you checkout
|
||
the code via `git clone`, this *gmock* directory won't exist and you will have to
|
||
download it manually or skip building protobuf unit-tests.
|
||
|
||
You can download gmock as follows:
|
||
|
||
C:\Path\to\protobuf>git clone -b release-1.7.0 https://github.com/google/googlemock.git gmock
|
||
|
||
Then go to *gmock* folder and download gtest:
|
||
|
||
C:\Path\to\protobuf>cd gmock
|
||
C:\Path\to\protobuf\gmock>git clone -b release-1.7.0 https://github.com/google/googletest.git gtest
|
||
|
||
If you absolutely don't want to build and run protobuf unit-tests, skip
|
||
this steps and use protobuf at your own risk.
|
||
|
||
Now go to *cmake* folder in protobuf sources:
|
||
|
||
C:\Path\to\protobuf\gmock>cd ..\cmake
|
||
C:\Path\to\protobuf\cmake>
|
||
|
||
Good. Now you are ready to *CMake* configuration.
|
||
|
||
CMake Configuration
|
||
===================
|
||
|
||
*CMake* supports a lot of different
|
||
[generators](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
|
||
for various native build systems.
|
||
We are only interested in
|
||
[Makefile](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#makefile-generators)
|
||
and
|
||
[Visual Studio](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators)
|
||
generators.
|
||
|
||
We will use shadow building to separate the temporary files from the protobuf source code.
|
||
|
||
Create a temporary *build* folder and change your working directory to it:
|
||
|
||
C:\Path\to\protobuf\cmake>mkdir build & cd build
|
||
C:\Path\to\protobuf\cmake\build>
|
||
|
||
The *Makefile* generator can build the project in only one configuration, so you need to build
|
||
a separate folder for each configuration.
|
||
|
||
To start using a *Release* configuration:
|
||
|
||
C:\Path\to\protobuf\cmake\build>mkdir release & cd release
|
||
C:\Path\to\protobuf\cmake\build\release>cmake -G "NMake Makefiles" ^
|
||
-DCMAKE_BUILD_TYPE=Release ^
|
||
-DCMAKE_INSTALL_PREFIX=../../../../install ^
|
||
../..
|
||
|
||
It will generate *nmake* *Makefile* in current directory.
|
||
|
||
To use *Debug* configuration:
|
||
|
||
C:\Path\to\protobuf\cmake\build>mkdir debug & cd debug
|
||
C:\Path\to\protobuf\cmake\build\debug>cmake -G "NMake Makefiles" ^
|
||
-DCMAKE_BUILD_TYPE=Debug ^
|
||
-DCMAKE_INSTALL_PREFIX=../../../../install ^
|
||
../..
|
||
|
||
It will generate *nmake* *Makefile* in current directory.
|
||
|
||
To create *Visual Studio* solution file:
|
||
|
||
C:\Path\to\protobuf\cmake\build>mkdir solution & cd solution
|
||
C:\Path\to\protobuf\cmake\build\solution>cmake -G "Visual Studio 12 2013 Win64" ^
|
||
-DCMAKE_INSTALL_PREFIX=../../../../install ^
|
||
../..
|
||
|
||
It will generate *Visual Studio* solution file *protobuf.sln* in current directory.
|
||
|
||
If the *gmock* directory does not exist, and you do not want to build protobuf unit tests,
|
||
you need to add *cmake* command argument `-Dprotobuf_BUILD_TESTS=OFF` to disable testing.
|
||
|
||
Compiling
|
||
=========
|
||
|
||
To compile protobuf:
|
||
|
||
C:\Path\to\protobuf\cmake\build\release>nmake
|
||
|
||
or
|
||
|
||
C:\Path\to\protobuf\cmake\build\debug>nmake
|
||
|
||
And wait for the compilation to finish.
|
||
|
||
If you prefer to use the IDE:
|
||
|
||
* Open the generated protobuf.sln file in Microsoft Visual Studio.
|
||
* Choose "Debug" or "Release" configuration as desired.
|
||
* From the Build menu, choose "Build Solution".
|
||
|
||
And wait for the compilation to finish.
|
||
|
||
Testing
|
||
=======
|
||
|
||
To run unit-tests:
|
||
|
||
C:\Path\to\protobuf\cmake\build\release>nmake check
|
||
|
||
or
|
||
|
||
C:\Path\to\protobuf\cmake\build\debug>nmake check
|
||
|
||
You can also build project *check* from Visual Studio solution.
|
||
Yes, it may sound strange, but it works.
|
||
|
||
You should see output similar to:
|
||
|
||
Running main() from gmock_main.cc
|
||
[==========] Running 1546 tests from 165 test cases.
|
||
|
||
...
|
||
|
||
[==========] 1546 tests from 165 test cases ran. (2529 ms total)
|
||
[ PASSED ] 1546 tests.
|
||
|
||
To run specific tests:
|
||
|
||
C:\Path\to\protobuf>cmake\build\release\tests.exe --gtest_filter=AnyTest*
|
||
Running main() from gmock_main.cc
|
||
Note: Google Test filter = AnyTest*
|
||
[==========] Running 3 tests from 1 test case.
|
||
[----------] Global test environment set-up.
|
||
[----------] 3 tests from AnyTest
|
||
[ RUN ] AnyTest.TestPackAndUnpack
|
||
[ OK ] AnyTest.TestPackAndUnpack (0 ms)
|
||
[ RUN ] AnyTest.TestPackAndUnpackAny
|
||
[ OK ] AnyTest.TestPackAndUnpackAny (0 ms)
|
||
[ RUN ] AnyTest.TestIs
|
||
[ OK ] AnyTest.TestIs (0 ms)
|
||
[----------] 3 tests from AnyTest (1 ms total)
|
||
|
||
[----------] Global test environment tear-down
|
||
[==========] 3 tests from 1 test case ran. (2 ms total)
|
||
[ PASSED ] 3 tests.
|
||
|
||
Note that the tests must be run from the source folder.
|
||
|
||
If all tests are passed, safely continue.
|
||
|
||
Installing
|
||
==========
|
||
|
||
To install protobuf to the specified *install* folder:
|
||
|
||
C:\Path\to\protobuf\cmake\build\release>nmake install
|
||
|
||
or
|
||
|
||
C:\Path\to\protobuf\cmake\build\debug>nmake install
|
||
|
||
You can also build project *INSTALL* from Visual Studio solution.
|
||
It sounds not so strange and it works.
|
||
|
||
This will create the following folders under the *install* location:
|
||
* bin - that contains protobuf *protoc.exe* compiler;
|
||
* include - that contains C++ headers and protobuf *.proto files;
|
||
* lib - that contains linking libraries and *CMake* configuration files for *protobuf* package.
|
||
|
||
Now you can if needed:
|
||
* Copy the contents of the include directory to wherever you want to put headers.
|
||
* Copy protoc.exe wherever you put build tools (probably somewhere in your PATH).
|
||
* Copy linking libraries libprotobuf[d].lib, libprotobuf-lite[d].lib, and libprotoc[d].lib wherever you put libraries.
|
||
|
||
To avoid conflicts between the MSVC debug and release runtime libraries, when
|
||
compiling a debug build of your application, you may need to link against a
|
||
debug build of libprotobufd.lib with "d" postfix. Similarly, release builds should link against
|
||
release libprotobuf.lib library.
|
||
|
||
DLLs vs. static linking
|
||
=======================
|
||
|
||
Static linking is now the default for the Protocol Buffer libraries. Due to
|
||
issues with Win32's use of a separate heap for each DLL, as well as binary
|
||
compatibility issues between different versions of MSVC's STL library, it is
|
||
recommended that you use static linkage only. However, it is possible to
|
||
build libprotobuf and libprotoc as DLLs if you really want. To do this,
|
||
do the following:
|
||
|
||
* Add an additional flag `-Dprotobuf_BUILD_SHARED_LIBS=ON` when invoking cmake
|
||
* Follow the same steps as described in the above section.
|
||
* When compiling your project, make sure to `#define PROTOBUF_USE_DLLS`.
|
||
|
||
When distributing your software to end users, we strongly recommend that you
|
||
do NOT install libprotobuf.dll or libprotoc.dll to any shared location.
|
||
Instead, keep these libraries next to your binaries, in your application's
|
||
own install directory. C++ makes it very difficult to maintain binary
|
||
compatibility between releases, so it is likely that future versions of these
|
||
libraries will *not* be usable as drop-in replacements.
|
||
|
||
If your project is itself a DLL intended for use by third-party software, we
|
||
recommend that you do NOT expose protocol buffer objects in your library's
|
||
public interface, and that you statically link protocol buffers into your
|
||
library.
|
||
|
||
ZLib support
|
||
============
|
||
|
||
If you want to include GzipInputStream and GzipOutputStream
|
||
(google/protobuf/io/gzip_stream.h) in libprotobuf, you will need to do a few
|
||
additional steps.
|
||
|
||
Obtain a copy of the zlib library. The pre-compiled DLL at zlib.net works.
|
||
You need prepare it:
|
||
|
||
* Make sure zlib's two headers are in your `C:\Path\to\install\include` path
|
||
* Make sure zlib's linking libraries (*.lib file) is in your
|
||
`C:\Path\to\install\lib` library path.
|
||
|
||
You can also compile it from source by yourself.
|
||
|
||
Getting sources:
|
||
|
||
C:\Path\to>git clone -b v1.2.8 https://github.com/madler/zlib.git
|
||
C:\Path\to>cd zlib
|
||
|
||
Compiling and Installing:
|
||
|
||
C:\Path\to\zlib>mkdir build & cd build
|
||
C:\Path\to\zlib\build>mkdir release & cd release
|
||
C:\Path\to\zlib\build\release>cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ^
|
||
-DCMAKE_INSTALL_PREFIX=../../../install ../..
|
||
C:\Path\to\zlib\build\release>nmake & nmake install
|
||
|
||
You can make *debug* version or use *Visual Studio* generator also as before for the
|
||
protobuf project.
|
||
|
||
Now add *bin* folder from *install* to system *PATH*:
|
||
|
||
C:\Path\to>set PATH=%PATH%;C:\Path\to\install\bin
|
||
|
||
You need reconfigure protobuf with flag `-Dprotobuf_WITH_ZLIB=ON` when invoking cmake.
|
||
|
||
Note that if you have compiled ZLIB yourself, as stated above,
|
||
further disable the option `-Dprotobuf_MSVC_STATIC_RUNTIME=OFF`.
|
||
|
||
If it reports NOTFOUND for zlib_include or zlib_lib, you might haven't put
|
||
the headers or the .lib file in the right directory.
|
||
|
||
Build and testing protobuf as usual.
|
||
|
||
Notes on Compiler Warnings
|
||
==========================
|
||
|
||
The following warnings have been disabled while building the protobuf libraries
|
||
and compiler. You may have to disable some of them in your own project as
|
||
well, or live with them.
|
||
|
||
* C4018 - 'expression' : signed/unsigned mismatch
|
||
* C4146 - unary minus operator applied to unsigned type, result still unsigned
|
||
* C4244 - Conversion from 'type1' to 'type2', possible loss of data.
|
||
* C4251 - 'identifier' : class 'type' needs to have dll-interface to be used by
|
||
clients of class 'type2'
|
||
* C4267 - Conversion from 'size_t' to 'type', possible loss of data.
|
||
* C4305 - 'identifier' : truncation from 'type1' to 'type2'
|
||
* C4355 - 'this' : used in base member initializer list
|
||
* C4800 - 'type' : forcing value to bool 'true' or 'false' (performance warning)
|
||
* C4996 - 'function': was declared deprecated
|
||
|
||
C4251 is of particular note, if you are compiling the Protocol Buffer library
|
||
as a DLL (see previous section). The protocol buffer library uses templates in
|
||
its public interfaces. MSVC does not provide any reasonable way to export
|
||
template classes from a DLL. However, in practice, it appears that exporting
|
||
templates is not necessary anyway. Since the complete definition of any
|
||
template is available in the header files, anyone importing the DLL will just
|
||
end up compiling instances of the templates into their own binary. The
|
||
Protocol Buffer implementation does not rely on static template members being
|
||
unique, so there should be no problem with this, but MSVC prints warning
|
||
nevertheless. So, we disable it. Unfortunately, this warning will also be
|
||
produced when compiling code which merely uses protocol buffers, meaning you
|
||
may have to disable it in your code too.
|