third_party/protobuf/README.txt

   1 Protocol Buffers - Google's data interchange format
   2 Copyright 2008 Google Inc.
   3 http://code.google.com/apis/protocolbuffers/
   4
   5 C++ Installation - Unix
   6 =======================
   7
   8 To build and install the C++ Protocol Buffer runtime and the Protocol
   9 Buffer compiler (protoc) execute the following:
  10
  11   $ ./configure
  12   $ make
  13   $ make check
  14   $ make install
  15
  16 If "make check" fails, you can still install, but it is likely that
  17 some features of this library will not work correctly on your system.
  18 Proceed at your own risk.
  19
  20 "make install" may require superuser privileges.
  21
  22 For advanced usage information on configure and make, see INSTALL.txt.
  23
  24 ** Hint on install location **
  25
  26   By default, the package will be installed to /usr/local.  However,
  27   on many platforms, /usr/local/lib is not part of LD_LIBRARY_PATH.
  28   You can add it, but it may be easier to just install to /usr
  29   instead.  To do this, invoke configure as follows:
  30
  31     ./configure --prefix=/usr
  32
  33   If you already built the package with a different prefix, make sure
  34   to run "make clean" before building again.
  35
  36 ** Compiling dependent packages **
  37
  38   To compile a package that uses Protocol Buffers, you need to pass
  39   various flags to your compiler and linker.  As of version 2.2.0,
  40   Protocol Buffers integrates with pkg-config to manage this.  If you
  41   have pkg-config installed, then you can invoke it to get a list of
  42   flags like so:
  43
  44     pkg-config --cflags protobuf         # print compiler flags
  45     pkg-config --libs protobuf           # print linker flags
  46     pkg-config --cflags --libs protobuf  # print both
  47
  48   For example:
  49
  50     c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf`
  51
  52   Note that packages written prior to the 2.2.0 release of Protocol
  53   Buffers may not yet integrate with pkg-config to get flags, and may
  54   not pass the correct set of flags to correctly link against
  55   libprotobuf.  If the package in question uses autoconf, you can
  56   often fix the problem by invoking its configure script like:
  57
  58     configure CXXFLAGS="$(pkg-config --cflags protobuf)" \
  59               LIBS="$(pkg-config --libs protobuf)"
  60
  61   This will force it to use the correct flags.
  62
  63   If you are writing an autoconf-based package that uses Protocol
  64   Buffers, you should probably use the PKG_CHECK_MODULES macro in your
  65   configure script like:
  66
  67     PKG_CHECK_MODULES([protobuf], [protobuf])
  68
  69   See the pkg-config man page for more info.
  70
  71   If you only want protobuf-lite, substitute "protobuf-lite" in place
  72   of "protobuf" in these examples.
  73
  74 ** Note for cross-compiling **
  75
  76   The makefiles normally invoke the protoc executable that they just
  77   built in order to build tests.  When cross-compiling, the protoc
  78   executable may not be executable on the host machine.  In this case,
  79   you must build a copy of protoc for the host machine first, then use
  80   the --with-protoc option to tell configure to use it instead.  For
  81   example:
  82
  83     ./configure --with-protoc=protoc
  84
  85   This will use the installed protoc (found in your $PATH) instead of
  86   trying to execute the one built during the build process.  You can
  87   also use an executable that hasn't been installed.  For example, if
  88   you built the protobuf package for your host machine in ../host,
  89   you might do:
  90
  91     ./configure --with-protoc=../host/src/protoc
  92
  93   Either way, you must make sure that the protoc executable you use
  94   has the same version as the protobuf source code you are trying to
  95   use it with.
  96
  97 ** Note for Solaris users **
  98
  99   Solaris 10 x86 has a bug that will make linking fail, complaining
 100   about libstdc++.la being invalid.  We have included a work-around
 101   in this package.  To use the work-around, run configure as follows:
 102
 103     ./configure LDFLAGS=-L$PWD/src/solaris
 104
 105   See src/solaris/libstdc++.la for more info on this bug.
 106
 107 ** Note for HP C++ Tru64 users **
 108
 109   To compile invoke configure as follows:
 110
 111     ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM"
 112
 113   Also, you will need to use gmake instead of make.
 114
 115 C++ Installation - Windows
 116 ==========================
 117
 118 If you are using Microsoft Visual C++, see vsprojects/readme.txt.
 119
 120 If you are using Cygwin or MinGW, follow the Unix installation
 121 instructions, above.
 122
 123 Binary Compatibility Warning
 124 ============================
 125
 126 Due to the nature of C++, it is unlikely that any two versions of the
 127 Protocol Buffers C++ runtime libraries will have compatible ABIs.
 128 That is, if you linked an executable against an older version of
 129 libprotobuf, it is unlikely to work with a newer version without
 130 re-compiling.  This problem, when it occurs, will normally be detected
 131 immediately on startup of your app.  Still, you may want to consider
 132 using static linkage.  You can configure this package to install
 133 static libraries only using:
 134
 135   ./configure --disable-shared
 136
 137 Java and Python Installation
 138 ============================
 139
 140 The Java and Python runtime libraries for Protocol Buffers are located
 141 in the java and python directories.  See the README file in each
 142 directory for more information on how to compile and install them.
 143 Note that both of them require you to first install the Protocol
 144 Buffer compiler (protoc), which is part of the C++ package.
 145
 146 Usage
 147 =====
 148
 149 The complete documentation for Protocol Buffers is available via the
 150 web at:
 151
 152   http://code.google.com/apis/protocolbuffers/