README.md

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