temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 1 | This directory contains project files for compiling Protocol Buffers using |
| 2 | MSVC. This is not the recommended way to do Protocol Buffer development -- |
| 3 | we prefer to develop under a Unix-like environment -- but it may be more |
| 4 | accessible to those who primarily work with MSVC. |
| 5 | |
| 6 | Compiling and Installing |
| 7 | ======================== |
| 8 | |
Feng Xiao | 78c8200 | 2014-12-11 15:36:08 -0800 | [diff] [blame] | 9 | 0) Check whether a gtest directory exists in the upper level directory. If |
| 10 | you checkout the code from github via "git clone", this gtest directory |
| 11 | won't exist and you won't be able to build the tests described below. To |
| 12 | avoid this problem consider downloading one of the release tar balls which |
| 13 | contains gtest already and copying the gest directory from there to your |
| 14 | protobuf directory: |
| 15 | https://github.com/google/protobuf/releases |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 16 | 1) Open protobuf.sln in Microsoft Visual Studio. |
temporal | cc93043 | 2008-07-21 20:28:30 +0000 | [diff] [blame] | 17 | 2) Choose "Debug" or "Release" configuration as desired.* |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 18 | 3) From the Build menu, choose "Build Solution". Wait for compiling to finish. |
kenton@google.com | e6607e3 | 2009-08-01 01:29:03 +0000 | [diff] [blame] | 19 | 4) From a command shell, run tests.exe and lite-test.exe and check that all |
| 20 | tests pass. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 21 | 5) Run extract_includes.bat to copy all the public headers into a separate |
| 22 | "include" directory (under the top-level package directory). |
| 23 | 6) Copy the contents of the include directory to wherever you want to put |
| 24 | headers. |
kenton@google.com | 580cf3c | 2008-10-21 17:18:26 +0000 | [diff] [blame] | 25 | 7) Copy protoc.exe wherever you put build tools (probably somewhere in your |
| 26 | PATH). |
kenton@google.com | e6607e3 | 2009-08-01 01:29:03 +0000 | [diff] [blame] | 27 | 8) Copy libprotobuf.lib, libprotobuf-lite.lib, and libprotoc.lib wherever you |
| 28 | put libraries. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 29 | |
temporal | cc93043 | 2008-07-21 20:28:30 +0000 | [diff] [blame] | 30 | * To avoid conflicts between the MSVC debug and release runtime libraries, when |
kenton@google.com | 580cf3c | 2008-10-21 17:18:26 +0000 | [diff] [blame] | 31 | compiling a debug build of your application, you may need to link against a |
| 32 | debug build of libprotobuf.lib. Similarly, release builds should link against |
| 33 | release libs. |
temporal | cc93043 | 2008-07-21 20:28:30 +0000 | [diff] [blame] | 34 | |
kenton@google.com | 9b10f58 | 2008-09-30 00:09:40 +0000 | [diff] [blame] | 35 | DLLs vs. static linking |
| 36 | ======================= |
| 37 | |
| 38 | Static linking is now the default for the Protocol Buffer libraries. Due to |
| 39 | issues with Win32's use of a separate heap for each DLL, as well as binary |
| 40 | compatibility issues between different versions of MSVC's STL library, it is |
| 41 | recommended that you use static linkage only. However, it is possible to |
| 42 | build libprotobuf and libprotoc as DLLs if you really want. To do this, |
| 43 | do the following: |
| 44 | |
| 45 | 1) Open protobuf.sln in MSVC. |
kenton@google.com | 9270a99 | 2009-08-01 02:16:55 +0000 | [diff] [blame] | 46 | 2) For each of the projects libprotobuf, libprotobuf-lite, and libprotoc, do |
| 47 | the following: |
kenton@google.com | 9b10f58 | 2008-09-30 00:09:40 +0000 | [diff] [blame] | 48 | 2a) Right-click the project and choose "properties". |
| 49 | 2b) From the side bar, choose "General", under "Configuration Properties". |
| 50 | 2c) Change the "Configuration Type" to "Dynamic Library (.dll)". |
| 51 | 2d) From the side bar, choose "Preprocessor", under "C/C++". |
| 52 | 2e) Add PROTOBUF_USE_DLLS to the list of preprocessor defines. |
| 53 | 3) When compiling your project, make sure to #define PROTOBUF_USE_DLLS. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 54 | |
| 55 | When distributing your software to end users, we strongly recommend that you |
| 56 | do NOT install libprotobuf.dll or libprotoc.dll to any shared location. |
| 57 | Instead, keep these libraries next to your binaries, in your application's |
| 58 | own install directory. C++ makes it very difficult to maintain binary |
| 59 | compatibility between releases, so it is likely that future versions of these |
kenton@google.com | 9b10f58 | 2008-09-30 00:09:40 +0000 | [diff] [blame] | 60 | libraries will *not* be usable as drop-in replacements. |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 61 | |
| 62 | If your project is itself a DLL intended for use by third-party software, we |
| 63 | recommend that you do NOT expose protocol buffer objects in your library's |
| 64 | public interface, and that you statically link protocol buffers into your |
| 65 | library. |
| 66 | |
kenton@google.com | 50ede8b | 2009-04-27 22:28:10 +0000 | [diff] [blame] | 67 | ZLib support |
| 68 | ============ |
| 69 | |
| 70 | If you want to include GzipInputStream and GzipOutputStream |
| 71 | (google/protobuf/io/gzip_stream.h) in libprotoc, you will need to do a few |
| 72 | additional steps: |
| 73 | |
| 74 | 1) Obtain a copy of the zlib library. The pre-compiled DLL at zlib.net works. |
| 75 | 2) Make sure zlib's two headers are in your include path and that the .lib file |
| 76 | is in your library path. You could place all three files directly into the |
| 77 | vsproject directory to compile libprotobuf, but they need to be visible to |
| 78 | your own project as well, so you should probably just put them into the |
| 79 | VC shared icnlude and library directories. |
| 80 | 3) Right-click on the "tests" project and choose "properties". Navigate the |
| 81 | sidebar to "Configuration Properties" -> "Linker" -> "Input". |
| 82 | 4) Under "Additional Dependencies", add the name of the zlib .lib file (e.g. |
| 83 | zdll.lib). Make sure to update both the Debug and Release configurations. |
| 84 | 5) If you are compiling libprotobuf and libprotoc as DLLs (see previous |
| 85 | section), repeat steps 2 and 3 for the libprotobuf and libprotoc projects. |
| 86 | If you are compiling them as static libraries, then you will need to link |
| 87 | against the zlib library directly from your own app. |
| 88 | 6) Edit config.h (in the vsprojects directory) and un-comment the line that |
| 89 | #defines HAVE_ZLIB. (Or, alternatively, define this macro via the project |
| 90 | settings.) |
| 91 | |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 92 | Notes on Compiler Warnings |
| 93 | ========================== |
| 94 | |
| 95 | The following warnings have been disabled while building the protobuf libraries |
| 96 | and compiler. You may have to disable some of them in your own project as |
| 97 | well, or live with them. |
| 98 | |
| 99 | C4018 - 'expression' : signed/unsigned mismatch |
| 100 | C4146 - unary minus operator applied to unsigned type, result still unsigned |
| 101 | C4244 - Conversion from 'type1' to 'type2', possible loss of data. |
| 102 | C4251 - 'identifier' : class 'type' needs to have dll-interface to be used by |
| 103 | clients of class 'type2' |
| 104 | C4267 - Conversion from 'size_t' to 'type', possible loss of data. |
| 105 | C4305 - 'identifier' : truncation from 'type1' to 'type2' |
| 106 | C4355 - 'this' : used in base member initializer list |
| 107 | C4800 - 'type' : forcing value to bool 'true' or 'false' (performance warning) |
| 108 | C4996 - 'function': was declared deprecated |
| 109 | |
kenton@google.com | 9b10f58 | 2008-09-30 00:09:40 +0000 | [diff] [blame] | 110 | C4251 is of particular note, if you are compiling the Protocol Buffer library |
| 111 | as a DLL (see previous section). The protocol buffer library uses templates in |
temporal | 40ee551 | 2008-07-10 02:12:20 +0000 | [diff] [blame] | 112 | its public interfaces. MSVC does not provide any reasonable way to export |
| 113 | template classes from a DLL. However, in practice, it appears that exporting |
| 114 | templates is not necessary anyway. Since the complete definition of any |
| 115 | template is available in the header files, anyone importing the DLL will just |
| 116 | end up compiling instances of the templates into their own binary. The |
| 117 | Protocol Buffer implementation does not rely on static template members being |
| 118 | unique, so there should be no problem with this, but MSVC prints warning |
| 119 | nevertheless. So, we disable it. Unfortunately, this warning will also be |
| 120 | produced when compiling code which merely uses protocol buffers, meaning you |
| 121 | may have to disable it in your code too. |