blob: 6d5430abb951ca53029caa4b6e80da584e7ac43c [file] [log] [blame]
Greg Steinf0d35d22009-01-30 19:10:27 +00001Apache Thrift (an Apache Incubator project)
Marc Slemko9de5a5c2006-08-23 22:34:00 +00002
Greg Steinf0d35d22009-01-30 19:10:27 +00003Last Modified: 2009-Jan-30
Marc Slemko9de5a5c2006-08-23 22:34:00 +00004
Greg Steinf0d35d22009-01-30 19:10:27 +00005Thrift is distributed under the Apache License, v2.0. Please see the
6included LICENSE file.
Marc Slemko9de5a5c2006-08-23 22:34:00 +00007
8Introduction
9============
10
Mark Slee57cc25e2007-02-28 21:43:54 +000011Thrift is a lightweight, language-independent software stack with an
Mark Slee3303f362007-03-05 20:09:37 +000012associated code generation mechanism for RPC. Thrift provides clean
13abstractions for data transport, data serialization, and application
14level processing. The code generation system takes a simple definition
15language as its input and generates code across programming languages that
16uses the abstracted stack to build interoperable RPC clients and servers.
17
Mark Slee227ac2c2007-03-07 05:46:50 +000018Thrift is specifically designed to support non-atomic version changes
19across client and server code.
20
Mark Slee3303f362007-03-05 20:09:37 +000021For more details on Thrift's design and implementation, take a gander at
22the Thrift whitepaper included in this distribution or at the README files
Mark Slee227ac2c2007-03-07 05:46:50 +000023in your particular subdirectory of interest.
Mark Slee3303f362007-03-05 20:09:37 +000024
25Heirarchy
26=========
27
28thrift/
29
30 compiler/
31 Contains the Thrift compiler, implemented in C++.
32
33 lib/
34 Contains the Thrift software library implementation, subdivided by
35 language of implementation.
36
37 cpp/
38 java/
39 php/
40 py/
Mark Slee227ac2c2007-03-07 05:46:50 +000041 rb/
Mark Slee3303f362007-03-05 20:09:37 +000042
43 test/
44
45 Contains sample Thrift files and test code across the target programming
46 languages.
47
Mark Slee227ac2c2007-03-07 05:46:50 +000048 tutorial/
49
50 Contains a basic tutorial that will teach you how to develop software
51 using Thrift.
Marc Slemko9de5a5c2006-08-23 22:34:00 +000052
53Requirements
54============
Mark Slee3303f362007-03-05 20:09:37 +000055
56Thrift requires boost shared pointers from boost-1.33.1 or greater, see:
57http://www.boost.org/libs/smart_ptr/smart_ptr.htm
58
59Some portions of Thrift also depend upon libevent, see:
60http://monkey.org/~provos/libevent/
61
David Reissb72d19f2007-09-18 19:46:00 +000062Some portions of Thrift also depend upon zlib, see:
63http://www.zlib.net/
64
Mark Slee3303f362007-03-05 20:09:37 +000065These libraries are open source and may be freely obtained, but they are not
66provided as a part of this distribution.
Marc Slemko9de5a5c2006-08-23 22:34:00 +000067
68Resources
69=========
70
71More information about Thrift can be obtained on the Thrift webpage at:
72
Greg Steinf0d35d22009-01-30 19:10:27 +000073 http://incubator.apache.org/thrift
Marc Slemko9de5a5c2006-08-23 22:34:00 +000074
75Acknowledgments
76===============
77
Greg Steinf0d35d22009-01-30 19:10:27 +000078Thrift was inspired by pillar, a lightweight RPC tool written by Adam D'Angelo,
79and also by Google's protocol buffers.
Marc Slemko9de5a5c2006-08-23 22:34:00 +000080
Mark Slee54b7ab92007-03-06 00:06:27 +000081Installation
Marc Slemko9de5a5c2006-08-23 22:34:00 +000082============
83
Mark Slee57cc25e2007-02-28 21:43:54 +000084If you are building from the first time out of the source repository, you will
David Reissb72d19f2007-09-18 19:46:00 +000085need to generate the configure scripts. (This is not necessary if you
86downloaded a tarball.) From the top directory, do:
Marc Slemko9de5a5c2006-08-23 22:34:00 +000087
88 ./bootstrap.sh
89
Mark Slee57cc25e2007-02-28 21:43:54 +000090Once the configure scripts are generated, thrift can be configured.
91From the top directory, do:
Marc Slemko9de5a5c2006-08-23 22:34:00 +000092
93 ./configure
94
Mark Slee57cc25e2007-02-28 21:43:54 +000095You may need to specify the location of the boost files explicitly.
Mark Slee3303f362007-03-05 20:09:37 +000096If you installed boost in /usr/local, you would run configure as follows:
Marc Slemko9de5a5c2006-08-23 22:34:00 +000097
98 ./configure --with-boost=/usr/local
99
Mark Slee3303f362007-03-05 20:09:37 +0000100Note that by default the thrift C++ library is typically built with debugging
101symbols included. If you want to customize these options you should use the
102CXXFLAGS option in configure, as such:
Mark Slee29050782006-09-29 00:12:30 +0000103
Mark Slee3303f362007-03-05 20:09:37 +0000104 ./configure CXXFLAGS='-g -O2'
Mark Slee57cc25e2007-02-28 21:43:54 +0000105 ./configure CFLAGS='-g -O2'
David Reissaea19c92007-08-29 23:17:32 +0000106 ./configure CPPFLAGS='-DDEBUG_MY_FEATURE'
Mark Slee29050782006-09-29 00:12:30 +0000107
Marc Slemko9de5a5c2006-08-23 22:34:00 +0000108Run ./configure --help to see other configuration options
109
David Reissaea19c92007-08-29 23:17:32 +0000110Please be aware that the Python library will ignore the --prefix option
111and just install wherever Python's distutils puts it (usually along
David Reissd6832192007-09-05 00:47:32 +0000112the lines of /usr/lib/pythonX.Y/site-packages/). If you need to control
113where the Python modules are installed, set the PY_PREFIX variable.
114(DESTDIR is respected for Python and C++.)
David Reissaea19c92007-08-29 23:17:32 +0000115
Mark Slee227ac2c2007-03-07 05:46:50 +0000116Make thrift:
Marc Slemko9de5a5c2006-08-23 22:34:00 +0000117
118 make
119
120From the top directory, become superuser and do:
121
122 make install
Mark Slee54b7ab92007-03-06 00:06:27 +0000123
Mark Slee227ac2c2007-03-07 05:46:50 +0000124Note that some language packages must be installed manually using build tools
125better suited to those languages (at the time of this writing, this applies
126to Java, Ruby, PHP).
127
Mark Slee54b7ab92007-03-06 00:06:27 +0000128Look for the README file in the lib/<language>/ folder for more details on the
129installation of each language library package.