blob: d84176e369ae38fc4e0f95b7915a3576082fc6a5 [file] [log] [blame] [view]
Feng Xiaod0e01142016-01-21 17:06:38 -08001Protocol Buffers - Google's data interchange format
2===================================================
3
Feng Xiaob4646ec2018-08-13 14:53:27 -07004[![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 Xiaod0e01142016-01-21 17:06:38 -08005
6Copyright 2008 Google Inc.
7
8https://developers.google.com/protocol-buffers/
9
10C++ Installation - Unix
11-----------------------
12
13To build protobuf from source, the following tools are needed:
14
15 * autoconf
16 * automake
17 * libtool
beardedn5rdb12f6302016-05-06 14:49:52 +020018 * make
beardedn5rd2eb774e2016-05-06 22:47:17 +020019 * g++
beardedn5rdb12f6302016-05-06 14:49:52 +020020 * unzip
Feng Xiaod0e01142016-01-21 17:06:38 -080021
Feng Xiao014e76e2018-03-29 12:11:50 -070022On Ubuntu/Debian, you can install them with:
Feng Xiaod0e01142016-01-21 17:06:38 -080023
Brent Shafferf8a969d2016-06-09 10:36:21 -070024 $ sudo apt-get install autoconf automake libtool curl make g++ unzip
Feng Xiaod0e01142016-01-21 17:06:38 -080025
26On other platforms, please use the corresponding package managing tool to
27install them before proceeding.
28
Feng Xiao014e76e2018-03-29 12:11:50 -070029To get the source, download one of the release .tar.gz or .zip packages in the
30release page:
Feng Xiaod0e01142016-01-21 17:06:38 -080031
Feng Xiaoafe98de2018-08-22 11:55:30 -070032 https://github.com/protocolbuffers/protobuf/releases/latest
Feng Xiao014e76e2018-03-29 12:11:50 -070033
34For example: if you only need C++, download `protobuf-cpp-[VERSION].tar.gz`; if
35you need C++ and Java, download `protobuf-java-[VERSION].tar.gz` (every package
36contains C++ source already); if you need C++ and multiple other languages,
37download `protobuf-all-[VERSION].tar.gz`.
38
39You can also get the source by "git clone" our git repository. Make sure you
40have also cloned the submodules and generated the configure script (skip this
41if you are using a release .tar.gz or .zip package):
42
Feng Xiaoafe98de2018-08-22 11:55:30 -070043 $ git clone https://github.com/protocolbuffers/protobuf.git
Feng Xiao014e76e2018-03-29 12:11:50 -070044 $ cd protobuf
Carlos O'Ryan3c5442a2018-03-26 16:54:32 -040045 $ git submodule update --init --recursive
Feng Xiaod0e01142016-01-21 17:06:38 -080046 $ ./autogen.sh
47
Feng Xiaod0e01142016-01-21 17:06:38 -080048To build and install the C++ Protocol Buffer runtime and the Protocol
49Buffer 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
57If "make check" fails, you can still install, but it is likely that
58some features of this library will not work correctly on your system.
59Proceed at your own risk.
60
61For advanced usage information on configure and make, please refer to the
62autoconf documentation:
63
Feng Xiao014e76e2018-03-29 12:11:50 -070064 http://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts
Feng Xiaod0e01142016-01-21 17:06:38 -080065
66**Hint on install location**
67
Feng Xiao014e76e2018-03-29 12:11:50 -070068By default, the package will be installed to /usr/local. However,
69on many platforms, /usr/local/lib is not part of LD_LIBRARY_PATH.
70You can add it, but it may be easier to just install to /usr
71instead. To do this, invoke configure as follows:
Feng Xiaod0e01142016-01-21 17:06:38 -080072
73 ./configure --prefix=/usr
74
Feng Xiao014e76e2018-03-29 12:11:50 -070075If you already built the package with a different prefix, make sure
76to run "make clean" before building again.
Feng Xiaod0e01142016-01-21 17:06:38 -080077
78**Compiling dependent packages**
79
Feng Xiao014e76e2018-03-29 12:11:50 -070080To compile a package that uses Protocol Buffers, you need to pass
81various flags to your compiler and linker. As of version 2.2.0,
82Protocol Buffers integrates with pkg-config to manage this. If you
83have pkg-config installed, then you can invoke it to get a list of
84flags like so:
Feng Xiaod0e01142016-01-21 17:06:38 -080085
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 Xiao014e76e2018-03-29 12:11:50 -070090For example:
Feng Xiaod0e01142016-01-21 17:06:38 -080091
92 c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf`
93
Feng Xiao014e76e2018-03-29 12:11:50 -070094Note that packages written prior to the 2.2.0 release of Protocol
95Buffers may not yet integrate with pkg-config to get flags, and may
96not pass the correct set of flags to correctly link against
97libprotobuf. If the package in question uses autoconf, you can
98often fix the problem by invoking its configure script like:
Feng Xiaod0e01142016-01-21 17:06:38 -080099
100 configure CXXFLAGS="$(pkg-config --cflags protobuf)" \
101 LIBS="$(pkg-config --libs protobuf)"
102
Feng Xiao014e76e2018-03-29 12:11:50 -0700103This will force it to use the correct flags.
Feng Xiaod0e01142016-01-21 17:06:38 -0800104
Feng Xiao014e76e2018-03-29 12:11:50 -0700105If you are writing an autoconf-based package that uses Protocol
106Buffers, you should probably use the PKG_CHECK_MODULES macro in your
107configure script like:
Feng Xiaod0e01142016-01-21 17:06:38 -0800108
109 PKG_CHECK_MODULES([protobuf], [protobuf])
110
Feng Xiao014e76e2018-03-29 12:11:50 -0700111See the pkg-config man page for more info.
Feng Xiaod0e01142016-01-21 17:06:38 -0800112
Feng Xiao014e76e2018-03-29 12:11:50 -0700113If you only want protobuf-lite, substitute "protobuf-lite" in place
114of "protobuf" in these examples.
Feng Xiaod0e01142016-01-21 17:06:38 -0800115
116**Note for Mac users**
117
Feng Xiao014e76e2018-03-29 12:11:50 -0700118For a Mac system, Unix tools are not available by default. You will first need
119to install Xcode from the Mac AppStore and then run the following command from
120a terminal:
Feng Xiaod0e01142016-01-21 17:06:38 -0800121
122 $ sudo xcode-select --install
123
Feng Xiao014e76e2018-03-29 12:11:50 -0700124To install Unix tools, you can install "port" following the instructions at
125https://www.macports.org . This will reside in /opt/local/bin/port for most
126Mac installations.
Feng Xiaod0e01142016-01-21 17:06:38 -0800127
128 $ sudo /opt/local/bin/port install autoconf automake libtool
129
Feng Xiao014e76e2018-03-29 12:11:50 -0700130Then follow the Unix instructions above.
Feng Xiaod0e01142016-01-21 17:06:38 -0800131
132**Note for cross-compiling**
133
Feng Xiao014e76e2018-03-29 12:11:50 -0700134The makefiles normally invoke the protoc executable that they just
135built in order to build tests. When cross-compiling, the protoc
136executable may not be executable on the host machine. In this case,
137you must build a copy of protoc for the host machine first, then use
138the --with-protoc option to tell configure to use it instead. For
139example:
Feng Xiaod0e01142016-01-21 17:06:38 -0800140
141 ./configure --with-protoc=protoc
142
Feng Xiao014e76e2018-03-29 12:11:50 -0700143This will use the installed protoc (found in your $PATH) instead of
144trying to execute the one built during the build process. You can
145also use an executable that hasn't been installed. For example, if
146you built the protobuf package for your host machine in ../host,
147you might do:
Feng Xiaod0e01142016-01-21 17:06:38 -0800148
149 ./configure --with-protoc=../host/src/protoc
150
Feng Xiao014e76e2018-03-29 12:11:50 -0700151Either way, you must make sure that the protoc executable you use
152has the same version as the protobuf source code you are trying to
153use it with.
Feng Xiaod0e01142016-01-21 17:06:38 -0800154
155**Note for Solaris users**
156
Feng Xiao014e76e2018-03-29 12:11:50 -0700157Solaris 10 x86 has a bug that will make linking fail, complaining
158about libstdc++.la being invalid. We have included a work-around
159in this package. To use the work-around, run configure as follows:
Feng Xiaod0e01142016-01-21 17:06:38 -0800160
161 ./configure LDFLAGS=-L$PWD/src/solaris
162
Feng Xiao014e76e2018-03-29 12:11:50 -0700163See src/solaris/libstdc++.la for more info on this bug.
Feng Xiaod0e01142016-01-21 17:06:38 -0800164
165**Note for HP C++ Tru64 users**
166
Feng Xiao014e76e2018-03-29 12:11:50 -0700167To compile invoke configure as follows:
Feng Xiaod0e01142016-01-21 17:06:38 -0800168
169 ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM"
170
Feng Xiao014e76e2018-03-29 12:11:50 -0700171Also, you will need to use gmake instead of make.
Feng Xiaod0e01142016-01-21 17:06:38 -0800172
173**Note for AIX users**
174
Feng Xiao014e76e2018-03-29 12:11:50 -0700175Compile using the IBM xlC C++ compiler as follows:
Feng Xiaod0e01142016-01-21 17:06:38 -0800176
177 ./configure CXX=xlC
178
Feng Xiao014e76e2018-03-29 12:11:50 -0700179Also, you will need to use GNU `make` (`gmake`) instead of AIX `make`.
Feng Xiaod0e01142016-01-21 17:06:38 -0800180
181C++ Installation - Windows
182--------------------------
183
184If you only need the protoc binary, you can download it from the release
185page:
186
Feng Xiaoafe98de2018-08-22 11:55:30 -0700187 https://github.com/protocolbuffers/protobuf/releases/latest
Feng Xiaod0e01142016-01-21 17:06:38 -0800188
189In the downloads section, download the zip file protoc-$VERSION-win32.zip.
190It contains the protoc binary as well as public proto files of protobuf
191library.
192
Robert Schumacheraaf41c62017-10-31 04:00:18 -0700193Protobuf and its dependencies can be installed directly by using `vcpkg`:
194
195 >vcpkg install protobuf protobuf:x64-windows
196
197If zlib support is desired, you'll also need to install the zlib feature:
198
199 >vcpkg install protobuf[zlib] protobuf[zlib]:x64-windows
200
201See https://github.com/Microsoft/vcpkg for more information.
202
Mahmut Ali Ă–ZKURAN9b3357d2016-05-06 10:16:28 +0300203To build from source using Microsoft Visual C++, see [cmake/README.md](../cmake/README.md).
Feng Xiaod0e01142016-01-21 17:06:38 -0800204
205To build from source using Cygwin or MinGW, follow the Unix installation
206instructions, above.
207
208Binary Compatibility Warning
209----------------------------
210
211Due to the nature of C++, it is unlikely that any two versions of the
212Protocol Buffers C++ runtime libraries will have compatible ABIs.
213That is, if you linked an executable against an older version of
214libprotobuf, it is unlikely to work with a newer version without
215re-compiling. This problem, when it occurs, will normally be detected
216immediately on startup of your app. Still, you may want to consider
217using static linkage. You can configure this package to install
218static libraries only using:
219
220 ./configure --disable-shared
221
222Usage
223-----
224
225The complete documentation for Protocol Buffers is available via the
226web at:
227
228 https://developers.google.com/protocol-buffers/