1Protocol Buffers - Google's data interchange format 2=================================================== 3 4Copyright 2008 Google Inc. 5 6https://developers.google.com/protocol-buffers/ 7 8C++ Installation - Unix 9----------------------- 10 11To build protobuf from source, the following tools are needed: 12 13 * autoconf 14 * automake 15 * libtool 16 * make 17 * g++ 18 * unzip 19 20On Ubuntu/Debian, you can install them with: 21 22 sudo apt-get install autoconf automake libtool curl make g++ unzip 23 24On other platforms, please use the corresponding package managing tool to 25install them before proceeding. 26 27To get the source, download one of the release .tar.gz or .zip packages in the 28release page: 29 30 https://github.com/protocolbuffers/protobuf/releases/latest 31 32For example: if you only need C++, download `protobuf-cpp-[VERSION].tar.gz`; if 33you need C++ and Java, download `protobuf-java-[VERSION].tar.gz` (every package 34contains C++ source already); if you need C++ and multiple other languages, 35download `protobuf-all-[VERSION].tar.gz`. 36 37You can also get the source by "git clone" our git repository. Make sure you 38have also cloned the submodules and generated the configure script (skip this 39if you are using a release .tar.gz or .zip package): 40 41 git clone https://github.com/protocolbuffers/protobuf.git 42 cd protobuf 43 git submodule update --init --recursive 44 ./autogen.sh 45 46To build and install the C++ Protocol Buffer runtime and the Protocol 47Buffer compiler (protoc) execute the following: 48 49 50 ./configure 51 make -j$(nproc) # $(nproc) ensures it uses all cores for compilation 52 make check 53 sudo make install 54 sudo ldconfig # refresh shared library cache. 55 56If "make check" fails, you can still install, but it is likely that 57some features of this library will not work correctly on your system. 58Proceed at your own risk. 59 60For advanced usage information on configure and make, please refer to the 61autoconf documentation: 62 63 http://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts 64 65**Hint on install location** 66 67By default, the package will be installed to /usr/local. However, 68on many platforms, /usr/local/lib is not part of LD_LIBRARY_PATH. 69You can add it, but it may be easier to just install to /usr 70instead. To do this, invoke configure as follows: 71 72 ./configure --prefix=/usr 73 74If you already built the package with a different prefix, make sure 75to run "make clean" before building again. 76 77**Compiling dependent packages** 78 79To compile a package that uses Protocol Buffers, you need to pass 80various flags to your compiler and linker. As of version 2.2.0, 81Protocol Buffers integrates with pkg-config to manage this. If you 82have pkg-config installed, then you can invoke it to get a list of 83flags like so: 84 85 86 pkg-config --cflags protobuf # print compiler flags 87 pkg-config --libs protobuf # print linker flags 88 pkg-config --cflags --libs protobuf # print both 89 90 91For example: 92 93 c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf` 94 95Note that packages written prior to the 2.2.0 release of Protocol 96Buffers may not yet integrate with pkg-config to get flags, and may 97not pass the correct set of flags to correctly link against 98libprotobuf. If the package in question uses autoconf, you can 99often fix the problem by invoking its configure script like: 100 101 102 configure CXXFLAGS="$(pkg-config --cflags protobuf)" \ 103 LIBS="$(pkg-config --libs protobuf)" 104 105This will force it to use the correct flags. 106 107If you are writing an autoconf-based package that uses Protocol 108Buffers, you should probably use the PKG_CHECK_MODULES macro in your 109configure script like: 110 111 PKG_CHECK_MODULES([protobuf], [protobuf]) 112 113See the pkg-config man page for more info. 114 115If you only want protobuf-lite, substitute "protobuf-lite" in place 116of "protobuf" in these examples. 117 118**Note for Mac users** 119 120For a Mac system, Unix tools are not available by default. You will first need 121to install Xcode from the Mac AppStore and then run the following command from 122a terminal: 123 124 sudo xcode-select --install 125 126To install Unix tools, you can install "port" following the instructions at 127https://www.macports.org . This will reside in /opt/local/bin/port for most 128Mac installations. 129 130 sudo /opt/local/bin/port install autoconf automake libtool 131 132Alternative for Homebrew users: 133 134 brew install autoconf automake libtool 135 136Then follow the Unix instructions above. 137 138**Note for cross-compiling** 139 140The makefiles normally invoke the protoc executable that they just 141built in order to build tests. When cross-compiling, the protoc 142executable may not be executable on the host machine. In this case, 143you must build a copy of protoc for the host machine first, then use 144the --with-protoc option to tell configure to use it instead. For 145example: 146 147 ./configure --with-protoc=protoc 148 149This will use the installed protoc (found in your $PATH) instead of 150trying to execute the one built during the build process. You can 151also use an executable that hasn't been installed. For example, if 152you built the protobuf package for your host machine in ../host, 153you might do: 154 155 ./configure --with-protoc=../host/src/protoc 156 157Either way, you must make sure that the protoc executable you use 158has the same version as the protobuf source code you are trying to 159use it with. 160 161**Note for Solaris users** 162 163Solaris 10 x86 has a bug that will make linking fail, complaining 164about libstdc++.la being invalid. We have included a work-around 165in this package. To use the work-around, run configure as follows: 166 167 ./configure LDFLAGS=-L$PWD/src/solaris 168 169See src/solaris/libstdc++.la for more info on this bug. 170 171**Note for HP C++ Tru64 users** 172 173To compile invoke configure as follows: 174 175 ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM" 176 177Also, you will need to use gmake instead of make. 178 179**Note for AIX users** 180 181Compile using the IBM xlC C++ compiler as follows: 182 183 ./configure CXX=xlC 184 185Also, you will need to use GNU `make` (`gmake`) instead of AIX `make`. 186 187C++ Installation - Windows 188-------------------------- 189 190If you only need the protoc binary, you can download it from the release 191page: 192 193 https://github.com/protocolbuffers/protobuf/releases/latest 194 195In the downloads section, download the zip file protoc-$VERSION-win32.zip. 196It contains the protoc binary as well as public proto files of protobuf 197library. 198 199Protobuf and its dependencies can be installed directly by using `vcpkg`: 200 201 >vcpkg install protobuf protobuf:x64-windows 202 203If zlib support is desired, you'll also need to install the zlib feature: 204 205 >vcpkg install protobuf[zlib] protobuf[zlib]:x64-windows 206 207See https://github.com/Microsoft/vcpkg for more information. 208 209To build from source using Microsoft Visual C++, see [cmake/README.md](../cmake/README.md). 210 211To build from source using Cygwin or MinGW, follow the Unix installation 212instructions, above. 213 214Binary Compatibility Warning 215---------------------------- 216 217Due to the nature of C++, it is unlikely that any two versions of the 218Protocol Buffers C++ runtime libraries will have compatible ABIs. 219That is, if you linked an executable against an older version of 220libprotobuf, it is unlikely to work with a newer version without 221re-compiling. This problem, when it occurs, will normally be detected 222immediately on startup of your app. Still, you may want to consider 223using static linkage. You can configure this package to install 224static libraries only using: 225 226 ./configure --disable-shared 227 228Usage 229----- 230 231The complete documentation for Protocol Buffers is available via the 232web at: 233 234https://developers.google.com/protocol-buffers/ 235