vsprojects/readme.txt

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