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 132Then follow the Unix instructions above. 133 134**Note for cross-compiling** 135 136The makefiles normally invoke the protoc executable that they just 137built in order to build tests. When cross-compiling, the protoc 138executable may not be executable on the host machine. In this case, 139you must build a copy of protoc for the host machine first, then use 140the --with-protoc option to tell configure to use it instead. For 141example: 142 143 ./configure --with-protoc=protoc 144 145This will use the installed protoc (found in your $PATH) instead of 146trying to execute the one built during the build process. You can 147also use an executable that hasn't been installed. For example, if 148you built the protobuf package for your host machine in ../host, 149you might do: 150 151 ./configure --with-protoc=../host/src/protoc 152 153Either way, you must make sure that the protoc executable you use 154has the same version as the protobuf source code you are trying to 155use it with. 156 157**Note for Solaris users** 158 159Solaris 10 x86 has a bug that will make linking fail, complaining 160about libstdc++.la being invalid. We have included a work-around 161in this package. To use the work-around, run configure as follows: 162 163 ./configure LDFLAGS=-L$PWD/src/solaris 164 165See src/solaris/libstdc++.la for more info on this bug. 166 167**Note for HP C++ Tru64 users** 168 169To compile invoke configure as follows: 170 171 ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM" 172 173Also, you will need to use gmake instead of make. 174 175**Note for AIX users** 176 177Compile using the IBM xlC C++ compiler as follows: 178 179 ./configure CXX=xlC 180 181Also, you will need to use GNU `make` (`gmake`) instead of AIX `make`. 182 183C++ Installation - Windows 184-------------------------- 185 186If you only need the protoc binary, you can download it from the release 187page: 188 189 https://github.com/protocolbuffers/protobuf/releases/latest 190 191In the downloads section, download the zip file protoc-$VERSION-win32.zip. 192It contains the protoc binary as well as public proto files of protobuf 193library. 194 195Protobuf and its dependencies can be installed directly by using `vcpkg`: 196 197 >vcpkg install protobuf protobuf:x64-windows 198 199If zlib support is desired, you'll also need to install the zlib feature: 200 201 >vcpkg install protobuf[zlib] protobuf[zlib]:x64-windows 202 203See https://github.com/Microsoft/vcpkg for more information. 204 205To build from source using Microsoft Visual C++, see [cmake/README.md](../cmake/README.md). 206 207To build from source using Cygwin or MinGW, follow the Unix installation 208instructions, above. 209 210Binary Compatibility Warning 211---------------------------- 212 213Due to the nature of C++, it is unlikely that any two versions of the 214Protocol Buffers C++ runtime libraries will have compatible ABIs. 215That is, if you linked an executable against an older version of 216libprotobuf, it is unlikely to work with a newer version without 217re-compiling. This problem, when it occurs, will normally be detected 218immediately on startup of your app. Still, you may want to consider 219using static linkage. You can configure this package to install 220static libraries only using: 221 222 ./configure --disable-shared 223 224Usage 225----- 226 227The complete documentation for Protocol Buffers is available via the 228web at: 229 230https://developers.google.com/protocol-buffers/ 231