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