diff options
Diffstat (limited to 'cmake/README.md')
| -rw-r--r-- | cmake/README.md | 336 |
1 files changed, 336 insertions, 0 deletions
diff --git a/cmake/README.md b/cmake/README.md new file mode 100644 index 00000000..1e7410d8 --- /dev/null +++ b/cmake/README.md @@ -0,0 +1,336 @@ +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, first you must compile protobuf as described above. +Then run: + + 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. |