README.md
1Protocol Buffers - Google's data interchange format
2===================================================
3
4[](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fubuntu%2Fcpp_distcheck%2Fcontinuous) [](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fubuntu%2Fbazel%2Fcontinuous) [](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fcpp%2Fcontinuous) [](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fcpp_distcheck%2Fcontinuous) [](https://ci.appveyor.com/project/protobuf/protobuf)
5
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
18 * make
19 * g++
20 * unzip
21
22On Ubuntu/Debian, you can install them with:
23
24 $ sudo apt-get install autoconf automake libtool curl make g++ unzip
25
26On other platforms, please use the corresponding package managing tool to
27install them before proceeding.
28
29To get the source, download one of the release .tar.gz or .zip packages in the
30release page:
31
32 https://github.com/protocolbuffers/protobuf/releases/latest
33
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
43 $ git clone https://github.com/protocolbuffers/protobuf.git
44 $ cd protobuf
45 $ git submodule update --init --recursive
46 $ ./autogen.sh
47
48To 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
64 http://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts
65
66**Hint on install location**
67
68By 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:
72
73 ./configure --prefix=/usr
74
75If you already built the package with a different prefix, make sure
76to run "make clean" before building again.
77
78**Compiling dependent packages**
79
80To 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:
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
90For example:
91
92 c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf`
93
94Note 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:
99
100 configure CXXFLAGS="$(pkg-config --cflags protobuf)" \
101 LIBS="$(pkg-config --libs protobuf)"
102
103This will force it to use the correct flags.
104
105If 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:
108
109 PKG_CHECK_MODULES([protobuf], [protobuf])
110
111See the pkg-config man page for more info.
112
113If you only want protobuf-lite, substitute "protobuf-lite" in place
114of "protobuf" in these examples.
115
116**Note for Mac users**
117
118For 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:
121
122 $ sudo xcode-select --install
123
124To 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.
127
128 $ sudo /opt/local/bin/port install autoconf automake libtool
129
130Then follow the Unix instructions above.
131
132**Note for cross-compiling**
133
134The 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:
140
141 ./configure --with-protoc=protoc
142
143This 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:
148
149 ./configure --with-protoc=../host/src/protoc
150
151Either 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.
154
155**Note for Solaris users**
156
157Solaris 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:
160
161 ./configure LDFLAGS=-L$PWD/src/solaris
162
163See src/solaris/libstdc++.la for more info on this bug.
164
165**Note for HP C++ Tru64 users**
166
167To compile invoke configure as follows:
168
169 ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM"
170
171Also, you will need to use gmake instead of make.
172
173**Note for AIX users**
174
175Compile using the IBM xlC C++ compiler as follows:
176
177 ./configure CXX=xlC
178
179Also, you will need to use GNU `make` (`gmake`) instead of AIX `make`.
180
181C++ Installation - Windows
182--------------------------
183
184If you only need the protoc binary, you can download it from the release
185page:
186
187 https://github.com/protocolbuffers/protobuf/releases/latest
188
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
193Protobuf 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
203To build from source using Microsoft Visual C++, see [cmake/README.md](../cmake/README.md).
204
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/
229
){kind=link}
){kind=link}
){kind=link}
){kind=link}