OLD | NEW |
1 Protocol Buffers - Google's data interchange format | 1 Protocol Buffers - Google's data interchange format |
2 =================================================== | 2 =================================================== |
3 | 3 |
4 [](https
://travis-ci.org/google/protobuf) [](https://ci.appveyor.com/project/proto
buf/protobuf) | 4 [](https
://travis-ci.org/google/protobuf) [](https://ci.appveyor.com/project/proto
buf/protobuf) |
5 | 5 |
6 Copyright 2008 Google Inc. | 6 Copyright 2008 Google Inc. |
7 | 7 |
8 https://developers.google.com/protocol-buffers/ | 8 https://developers.google.com/protocol-buffers/ |
9 | 9 |
10 C++ Installation - Unix | 10 Overview |
11 ----------------------- | 11 -------- |
12 | 12 |
13 If you get the source from github, you need to generate the configure script | 13 Protocol Buffers (a.k.a., protobuf) are Google's language-neutral, |
14 first: | 14 platform-neutral, extensible mechanism for serializing structured data. You |
| 15 can find [protobuf's documentation on the Google Developers site](https://develo
pers.google.com/protocol-buffers/). |
15 | 16 |
16 $ ./autogen.sh | 17 This README file contains protobuf installation instructions. To install |
| 18 protobuf, you need to install the protocol compiler (used to compile .proto |
| 19 files) and the protobuf runtime for your chosen programming language. |
17 | 20 |
18 This will download gmock source (which is used for C++ Protocol Buffer | 21 Protocol Compiler Installation |
19 unit-tests) to the current directory and run automake, autoconf, etc. | 22 ------------------------------ |
20 to generate the configure script and various template makefiles. | |
21 | 23 |
22 You can skip this step if you are using a release package (which already | 24 The protocol compiler is written in C++. If you are using C++, please follow |
23 contains gmock and the configure script). | 25 the [C++ Installation Instructions](src/README.md) to install protoc along |
| 26 with the C++ runtime. |
24 | 27 |
25 To build and install the C++ Protocol Buffer runtime and the Protocol | 28 For non-C++ users, the simplest way to install the protocol compiler is to |
26 Buffer compiler (protoc) execute the following: | 29 download a pre-built binary from our release page: |
27 | 30 |
28 $ ./configure | 31 [https://github.com/google/protobuf/releases](https://github.com/google/protob
uf/releases) |
29 $ make | |
30 $ make check | |
31 $ make install | |
32 | 32 |
33 If "make check" fails, you can still install, but it is likely that | 33 In the downloads section of each release, you can find pre-built binaries in |
34 some features of this library will not work correctly on your system. | 34 zip packages: protoc-$VERSION-$PLATFORM.zip. It contains the protoc binary |
35 Proceed at your own risk. | 35 as well as a set of standard .proto files distributed along with protobuf. |
36 | 36 |
37 "make install" may require superuser privileges. | 37 If you are looking for an old version that is not available in the release |
| 38 page, check out the maven repo here: |
38 | 39 |
39 For advanced usage information on configure and make, see INSTALL.txt. | 40 [http://repo1.maven.org/maven2/com/google/protobuf/protoc/](http://repo1.maven
.org/maven2/com/google/protobuf/protoc/) |
40 | 41 |
41 **Hint on install location** | 42 These pre-built binaries are only provided for released versions. If you want |
| 43 to use the github master version at HEAD, or you need to modify protobuf code, |
| 44 or you are using C++, it's recommended to build your own protoc binary from |
| 45 source. |
42 | 46 |
43 By default, the package will be installed to /usr/local. However, | 47 If you would like to build protoc binary from source, see the [C++ Installation |
44 on many platforms, /usr/local/lib is not part of LD_LIBRARY_PATH. | 48 Instructions](src/README.md). |
45 You can add it, but it may be easier to just install to /usr | |
46 instead. To do this, invoke configure as follows: | |
47 | 49 |
48 ./configure --prefix=/usr | 50 Protobuf Runtime Installation |
| 51 ----------------------------- |
49 | 52 |
50 If you already built the package with a different prefix, make sure | 53 Protobuf supports several different programming languages. For each programming |
51 to run "make clean" before building again. | 54 language, you can find instructions in the corresponding source directory about |
| 55 how to install protobuf runtime for that specific language: |
52 | 56 |
53 **Compiling dependent packages** | 57 | Language | Source
| |
| 58 |--------------------------------------|----------------------------------------
---------------| |
| 59 | C++ (include C++ runtime and protoc) | [src](src)
| |
| 60 | Java | [java](java)
| |
| 61 | Python | [python](python)
| |
| 62 | Objective-C | [objectivec](objectivec)
| |
| 63 | C# | [csharp](csharp)
| |
| 64 | JavaNano | [javanano](javanano)
| |
| 65 | JavaScript | [js](js)
| |
| 66 | Ruby | [ruby](ruby)
| |
| 67 | Go | [golang/protobuf](https://github.com/go
lang/protobuf) | |
| 68 | PHP | TBD
| |
54 | 69 |
55 To compile a package that uses Protocol Buffers, you need to pass | |
56 various flags to your compiler and linker. As of version 2.2.0, | |
57 Protocol Buffers integrates with pkg-config to manage this. If you | |
58 have pkg-config installed, then you can invoke it to get a list of | |
59 flags like so: | |
60 | |
61 pkg-config --cflags protobuf # print compiler flags | |
62 pkg-config --libs protobuf # print linker flags | |
63 pkg-config --cflags --libs protobuf # print both | |
64 | |
65 For example: | |
66 | |
67 c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf` | |
68 | |
69 Note that packages written prior to the 2.2.0 release of Protocol | |
70 Buffers may not yet integrate with pkg-config to get flags, and may | |
71 not pass the correct set of flags to correctly link against | |
72 libprotobuf. If the package in question uses autoconf, you can | |
73 often fix the problem by invoking its configure script like: | |
74 | |
75 configure CXXFLAGS="$(pkg-config --cflags protobuf)" \ | |
76 LIBS="$(pkg-config --libs protobuf)" | |
77 | |
78 This will force it to use the correct flags. | |
79 | |
80 If you are writing an autoconf-based package that uses Protocol | |
81 Buffers, you should probably use the PKG_CHECK_MODULES macro in your | |
82 configure script like: | |
83 | |
84 PKG_CHECK_MODULES([protobuf], [protobuf]) | |
85 | |
86 See the pkg-config man page for more info. | |
87 | |
88 If you only want protobuf-lite, substitute "protobuf-lite" in place | |
89 of "protobuf" in these examples. | |
90 | |
91 **Note for Mac users** | |
92 | |
93 For a Mac system, Unix tools are not available by default. You will first need | |
94 to install Xcode from the Mac AppStore and then run the following command from | |
95 a terminal: | |
96 | |
97 $ sudo xcode-select --install | |
98 | |
99 To install Unix tools, you can install "port" following the instructions at | |
100 https://www.macports.org . This will reside in /opt/local/bin/port for most | |
101 Mac installations. | |
102 | |
103 $ sudo /opt/local/bin/port install autoconf automake libtool | |
104 | |
105 Then follow the Unix instructions above. | |
106 | |
107 **Note for cross-compiling** | |
108 | |
109 The makefiles normally invoke the protoc executable that they just | |
110 built in order to build tests. When cross-compiling, the protoc | |
111 executable may not be executable on the host machine. In this case, | |
112 you must build a copy of protoc for the host machine first, then use | |
113 the --with-protoc option to tell configure to use it instead. For | |
114 example: | |
115 | |
116 ./configure --with-protoc=protoc | |
117 | |
118 This will use the installed protoc (found in your $PATH) instead of | |
119 trying to execute the one built during the build process. You can | |
120 also use an executable that hasn't been installed. For example, if | |
121 you built the protobuf package for your host machine in ../host, | |
122 you might do: | |
123 | |
124 ./configure --with-protoc=../host/src/protoc | |
125 | |
126 Either way, you must make sure that the protoc executable you use | |
127 has the same version as the protobuf source code you are trying to | |
128 use it with. | |
129 | |
130 **Note for Solaris users** | |
131 | |
132 Solaris 10 x86 has a bug that will make linking fail, complaining | |
133 about libstdc++.la being invalid. We have included a work-around | |
134 in this package. To use the work-around, run configure as follows: | |
135 | |
136 ./configure LDFLAGS=-L$PWD/src/solaris | |
137 | |
138 See src/solaris/libstdc++.la for more info on this bug. | |
139 | |
140 **Note for HP C++ Tru64 users** | |
141 | |
142 To compile invoke configure as follows: | |
143 | |
144 ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM" | |
145 | |
146 Also, you will need to use gmake instead of make. | |
147 | |
148 **Note for AIX users** | |
149 | |
150 Compile using the IBM xlC C++ compiler as follows: | |
151 | |
152 ./configure CXX=xlC | |
153 | |
154 Also, you will need to use GNU `make` (`gmake`) instead of AIX `make`. | |
155 | |
156 C++ Installation - Windows | |
157 -------------------------- | |
158 | |
159 If you are using Microsoft Visual C++, see cmake/README.md. | |
160 | |
161 If you are using Cygwin or MinGW, follow the Unix installation | |
162 instructions, above. | |
163 | |
164 Binary Compatibility Warning | |
165 ---------------------------- | |
166 | |
167 Due to the nature of C++, it is unlikely that any two versions of the | |
168 Protocol Buffers C++ runtime libraries will have compatible ABIs. | |
169 That is, if you linked an executable against an older version of | |
170 libprotobuf, it is unlikely to work with a newer version without | |
171 re-compiling. This problem, when it occurs, will normally be detected | |
172 immediately on startup of your app. Still, you may want to consider | |
173 using static linkage. You can configure this package to install | |
174 static libraries only using: | |
175 | |
176 ./configure --disable-shared | |
177 | |
178 Java and Python Installation | |
179 ---------------------------- | |
180 | |
181 The Java and Python runtime libraries for Protocol Buffers are located | |
182 in the java and python directories. See the README file in each | |
183 directory for more information on how to compile and install them. | |
184 Note that both of them require you to first install the Protocol | |
185 Buffer compiler (protoc), which is part of the C++ package. | |
186 | 70 |
187 Usage | 71 Usage |
188 ----- | 72 ----- |
189 | 73 |
190 The complete documentation for Protocol Buffers is available via the | 74 The complete documentation for Protocol Buffers is available via the |
191 web at: | 75 web at: |
192 | 76 |
193 https://developers.google.com/protocol-buffers/ | 77 https://developers.google.com/protocol-buffers/ |
OLD | NEW |