README.txt revision 3551c9c881056c480085172ff9840cab31610854
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Protocol Buffers - Google's data interchange format 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Copyright 2008 Google Inc. 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)http://code.google.com/apis/protocolbuffers/ 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)C++ Installation - Unix 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)======================= 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)To build and install the C++ Protocol Buffer runtime and the Protocol 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Buffer compiler (protoc) execute the following: 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) $ ./configure 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) $ make 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) $ make check 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) $ make install 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If "make check" fails, you can still install, but it is likely that 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)some features of this library will not work correctly on your system. 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Proceed at your own risk. 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)"make install" may require superuser privileges. 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)For advanced usage information on configure and make, see INSTALL.txt. 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Hint on install location ** 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) By default, the package will be installed to /usr/local. However, 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) on many platforms, /usr/local/lib is not part of LD_LIBRARY_PATH. 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) You can add it, but it may be easier to just install to /usr 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) instead. To do this, invoke configure as follows: 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure --prefix=/usr 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you already built the package with a different prefix, make sure 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) to run "make clean" before building again. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Compiling dependent packages ** 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) To compile a package that uses Protocol Buffers, you need to pass 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) various flags to your compiler and linker. As of version 2.2.0, 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Protocol Buffers integrates with pkg-config to manage this. If you 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) have pkg-config installed, then you can invoke it to get a list of 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) flags like so: 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) pkg-config --cflags protobuf # print compiler flags 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) pkg-config --libs protobuf # print linker flags 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) pkg-config --cflags --libs protobuf # print both 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) For example: 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf` 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Note that packages written prior to the 2.2.0 release of Protocol 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Buffers may not yet integrate with pkg-config to get flags, and may 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) not pass the correct set of flags to correctly link against 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) libprotobuf. If the package in question uses autoconf, you can 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) often fix the problem by invoking its configure script like: 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) configure CXXFLAGS="$(pkg-config --cflags protobuf)" \ 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) LIBS="$(pkg-config --libs protobuf)" 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) This will force it to use the correct flags. 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you are writing an autoconf-based package that uses Protocol 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Buffers, you should probably use the PKG_CHECK_MODULES macro in your 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) configure script like: 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PKG_CHECK_MODULES([protobuf], [protobuf]) 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) See the pkg-config man page for more info. 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If you only want protobuf-lite, substitute "protobuf-lite" in place 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) of "protobuf" in these examples. 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Note for cross-compiling ** 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) The makefiles normally invoke the protoc executable that they just 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) built in order to build tests. When cross-compiling, the protoc 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) executable may not be executable on the host machine. In this case, 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) you must build a copy of protoc for the host machine first, then use 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) the --with-protoc option to tell configure to use it instead. For 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) example: 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure --with-protoc=protoc 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) This will use the installed protoc (found in your $PATH) instead of 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) trying to execute the one built during the build process. You can 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) also use an executable that hasn't been installed. For example, if 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) you built the protobuf package for your host machine in ../host, 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) you might do: 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure --with-protoc=../host/src/protoc 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Either way, you must make sure that the protoc executable you use 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) has the same version as the protobuf source code you are trying to 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) use it with. 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Note for Solaris users ** 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Solaris 10 x86 has a bug that will make linking fail, complaining 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) about libstdc++.la being invalid. We have included a work-around 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) in this package. To use the work-around, run configure as follows: 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure LDFLAGS=-L$PWD/src/solaris 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) See src/solaris/libstdc++.la for more info on this bug. 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** Note for HP C++ Tru64 users ** 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) To compile invoke configure as follows: 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure CXXFLAGS="-O -std ansi -ieee -D__USE_STD_IOSTREAM" 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Also, you will need to use gmake instead of make. 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)C++ Installation - Windows 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)========================== 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1183551c9c881056c480085172ff9840cab31610854Torne (Richard Coles)If you are using Microsoft Visual C++, see vsprojects/readme.txt. 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)If you are using Cygwin or MinGW, follow the Unix installation 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)instructions, above. 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Binary Compatibility Warning 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)============================ 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Due to the nature of C++, it is unlikely that any two versions of the 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Protocol Buffers C++ runtime libraries will have compatible ABIs. 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)That is, if you linked an executable against an older version of 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)libprotobuf, it is unlikely to work with a newer version without 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)re-compiling. This problem, when it occurs, will normally be detected 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)immediately on startup of your app. Still, you may want to consider 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)using static linkage. You can configure this package to install 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)static libraries only using: 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ./configure --disable-shared 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Java and Python Installation 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)============================ 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The Java and Python runtime libraries for Protocol Buffers are located 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)in the java and python directories. See the README file in each 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)directory for more information on how to compile and install them. 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Note that both of them require you to first install the Protocol 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Buffer compiler (protoc), which is part of the C++ package. 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Usage 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)===== 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)The complete documentation for Protocol Buffers is available via the 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)web at: 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) http://code.google.com/apis/protocolbuffers/ 153