Merge pull request #457 from xfxyjwf/cmake

Add cmake support.

1 files changed, 127 insertions, 0 deletions

diff --git a/cmake/README.md b/cmake/README.md
new file mode 100644
index 00000000..02798b63
--- /dev/null
+++ b/cmake/README.md
@@ -0,0 +1,127 @@
+This directory contains cmake files that can be used to generate MSVC project
+files in order to build protobuf on windows. You need to have cmake installed
+on your computer before proceeding.
+
+Compiling and Installing
+========================
+
+1. Check whether a gtest directory exists in the upper level directory. If
+   you checkout the code from github via "git clone", this gtest directory
+   won't exist and you won't be able to build the tests described below. To
+   avoid this problem consider downloading one of the release tar balls which
+   contains gtest already and copying the gest directory from there to your
+   protobuf directory:
+
+        https://github.com/google/protobuf/releases
+
+2. Use cmake to generate MSVC project files. Running the following commands
+   in a command shell will generate project files for Visual Studio 2008 in
+   a sub-directory named "build".
+
+        $ cd path/to/protobuf/cmake
+        $ mkdir build
+        $ cd build
+        $ cmake -G "Visual Studio 9 2008" ..
+
+3. Open the generated protobuf.sln file in Microsoft Visual Studio.
+4. Choose "Debug" or "Release" configuration as desired.
+5. From the Build menu, choose "Build Solution".  Wait for compiling to finish.
+6. From a command shell, run tests.exe and lite-test.exe and check that all
+   tests pass. Make sure you have changed the working directory to the output
+   directory because tests.exe will try to find and run test_plugin.exe
+   in the working directory.
+7. Run extract_includes.bat to copy all the public headers into a separate
+   "include" directory (under the top-level package directory).
+8. Copy the contents of the include directory to wherever you want to put
+   headers.
+9. Copy protoc.exe wherever you put build tools (probably somewhere in your
+   PATH).
+10. Copy libprotobuf.lib, libprotobuf-lite.lib, and libprotoc.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 libprotobuf.lib.  Similarly, release builds should link against
+  release libs.
+
+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:
+
+  1. Add an additional flag "-DBUILD_SHARED_LIBS=ON" when invoking cmake:
+
+        $ cmake -G "Visual Studio 9 2008" -DBUILD_SHARED_LIBS=ON ..
+
+  2. Follow the same steps as described in the above section.
+  3. 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:
+
+1. Obtain a copy of the zlib library.  The pre-compiled DLL at zlib.net works.
+2. Make sure zlib's two headers are in your include path and that the .lib file
+   is in your library path.  You could place all three files directly into this
+   cmake directory to compile libprotobuf, but they need to be visible to
+   your own project as well, so you should probably just put them into the
+   VC shared icnlude and library directories.
+3. Add flag "-DZLIB=ON" when invoking cmake:
+
+        $ cmake -G "Visual Studio 9 2008" -DZLIB=ON ..
+
+   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.
+4) Open the generated protobuf.sln file and build 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.
+