Wink Saville | fbaaef9 | 2010-05-27 16:25:37 -0700 | [diff] [blame] | 1 | Protocol Buffers - Google's data interchange format |
| 2 | Copyright 2008 Google Inc. |
| 3 | http://code.google.com/apis/protocolbuffers/ |
| 4 | |
| 5 | C++ Installation - Unix |
| 6 | ======================= |
| 7 | |
| 8 | To build and install the C++ Protocol Buffer runtime and the Protocol |
| 9 | Buffer compiler (protoc) execute the following: |
| 10 | |
| 11 | $ ./configure |
| 12 | $ make |
| 13 | $ make check |
| 14 | $ make install |
| 15 | |
| 16 | If "make check" fails, you can still install, but it is likely that |
| 17 | some features of this library will not work correctly on your system. |
| 18 | Proceed at your own risk. |
| 19 | |
| 20 | "make install" may require superuser privileges. |
| 21 | |
| 22 | For advanced usage information on configure and make, see INSTALL.txt. |
| 23 | |
| 24 | ** Hint on install location ** |
| 25 | |
| 26 | By default, the package will be installed to /usr/local. However, |
| 27 | on many platforms, /usr/local/lib is not part of LD_LIBRARY_PATH. |
| 28 | You can add it, but it may be easier to just install to /usr |
| 29 | instead. To do this, invoke configure as follows: |
| 30 | |
| 31 | ./configure --prefix=/usr |
| 32 | |
| 33 | If you already built the package with a different prefix, make sure |
| 34 | to run "make clean" before building again. |
| 35 | |
| 36 | ** Compiling dependent packages ** |
| 37 | |
| 38 | To compile a package that uses Protocol Buffers, you need to pass |
| 39 | various flags to your compiler and linker. As of version 2.2.0, |
| 40 | Protocol Buffers integrates with pkg-config to manage this. If you |
| 41 | have pkg-config installed, then you can invoke it to get a list of |
| 42 | flags like so: |
| 43 | |
| 44 | pkg-config --cflags protobuf # print compiler flags |
| 45 | pkg-config --libs protobuf # print linker flags |
| 46 | pkg-config --cflags --libs protobuf # print both |
| 47 | |
| 48 | For example: |
| 49 | |
| 50 | c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf` |
| 51 | |
| 52 | Note that packages written prior to the 2.2.0 release of Protocol |
| 53 | Buffers may not yet integrate with pkg-config to get flags, and may |
| 54 | not pass the correct set of flags to correctly link against |
| 55 | libprotobuf. If the package in question uses autoconf, you can |
| 56 | often fix the problem by invoking its configure script like: |
| 57 | |
| 58 | configure CXXFLAGS="$(pkg-config --cflags protobuf)" \ |
| 59 | LIBS="$(pkg-config --libs protobuf)" |
| 60 | |
| 61 | This will force it to use the correct flags. |
| 62 | |
| 63 | If you are writing an autoconf-based package that uses Protocol |
| 64 | Buffers, you should probably use the PKG_CHECK_MODULES macro in your |
| 65 | configure script like: |
| 66 | |
| 67 | PKG_CHECK_MODULES([protobuf], [protobuf]) |
| 68 | |
| 69 | See the pkg-config man page for more info. |
| 70 | |
| 71 | If you only want protobuf-lite, substitute "protobuf-lite" in place |
| 72 | of "protobuf" in these examples. |
| 73 | |
| 74 | ** Note for cross-compiling ** |
| 75 | |
| 76 | The makefiles normally invoke the protoc executable that they just |
| 77 | built in order to build tests. When cross-compiling, the protoc |
| 78 | executable may not be executable on the host machine. In this case, |
| 79 | you must build a copy of protoc for the host machine first, then use |
| 80 | the --with-protoc option to tell configure to use it instead. For |
| 81 | example: |
| 82 | |
| 83 | ./configure --with-protoc=protoc |
| 84 | |
| 85 | This will use the installed protoc (found in your $PATH) instead of |
| 86 | trying to execute the one built during the build process. You can |
| 87 | also use an executable that hasn't been installed. For example, if |
| 88 | you built the protobuf package for your host machine in ../host, |
| 89 | you might do: |
| 90 | |
| 91 | ./configure --with-protoc=../host/src/protoc |
| 92 | |
| 93 | Either way, you must make sure that the protoc executable you use |
| 94 | has the same version as the protobuf source code you are trying to |
| 95 | use it with. |
| 96 | |
| 97 | ** Note for Solaris users ** |
| 98 | |
| 99 | Solaris 10 x86 has a bug that will make linking fail, complaining |
| 100 | about libstdc++.la being invalid. We have included a work-around |
| 101 | in this package. To use the work-around, run configure as follows: |
| 102 | |
| 103 | ./configure LDFLAGS=-L$PWD/src/solaris |
| 104 | |
| 105 | See src/solaris/libstdc++.la for more info on this bug. |
| 106 | |
| 107 | ** Note for HP C++ Tru64 users ** |
| 108 | |
| 109 | To compile invoke configure as follows: |
| 110 | |
| 111 | ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM" |
| 112 | |
| 113 | Also, you will need to use gmake instead of make. |
| 114 | |
| 115 | C++ Installation - Windows |
| 116 | ========================== |
| 117 | |
| 118 | If you are using Micosoft Visual C++, see vsprojects/readme.txt. |
| 119 | |
| 120 | If you are using Cygwin or MinGW, follow the Unix installation |
| 121 | instructions, above. |
| 122 | |
| 123 | Binary Compatibility Warning |
| 124 | ============================ |
| 125 | |
| 126 | Due to the nature of C++, it is unlikely that any two versions of the |
| 127 | Protocol Buffers C++ runtime libraries will have compatible ABIs. |
| 128 | That is, if you linked an executable against an older version of |
| 129 | libprotobuf, it is unlikely to work with a newer version without |
| 130 | re-compiling. This problem, when it occurs, will normally be detected |
| 131 | immediately on startup of your app. Still, you may want to consider |
| 132 | using static linkage. You can configure this package to install |
| 133 | static libraries only using: |
| 134 | |
| 135 | ./configure --disable-shared |
| 136 | |
| 137 | Java and Python Installation |
| 138 | ============================ |
| 139 | |
| 140 | The Java and Python runtime libraries for Protocol Buffers are located |
| 141 | in the java and python directories. See the README file in each |
| 142 | directory for more information on how to compile and install them. |
| 143 | Note that both of them require you to first install the Protocol |
| 144 | Buffer compiler (protoc), which is part of the C++ package. |
| 145 | |
| 146 | Usage |
| 147 | ===== |
| 148 | |
| 149 | The complete documentation for Protocol Buffers is available via the |
| 150 | web at: |
| 151 | |
| 152 | http://code.google.com/apis/protocolbuffers/ |