Merge commit 'remotes/trunk'
[amiethrift.git] / README
blob72062592ea737770946fa039eb4f890157f0f861
1 Thrift (Thrift IDL and RPC tool)
3 Mark Slee (mcslee@facebook.com)
4 Marc Kwiatkowski (marc@facebook.com)
5 Aditya Agarwal (aditya@facebook.com)
7 Last Modified: 2007-Mar-06
9 Thrift is distributed under the Thrift open source software license.
10 Please see the included LICENSE file.
12 Introduction
13 ============
15 Thrift is a lightweight, language-independent software stack with an
16 associated code generation mechanism for RPC. Thrift provides clean
17 abstractions for data transport, data serialization, and application
18 level processing. The code generation system takes a simple definition
19 language as its input and generates code across programming languages that
20 uses the abstracted stack to build interoperable RPC clients and servers.
22 Thrift is specifically designed to support non-atomic version changes
23 across client and server code.
25 For more details on Thrift's design and implementation, take a gander at
26 the Thrift whitepaper included in this distribution or at the README files
27 in your particular subdirectory of interest.
29 Heirarchy
30 =========
32 thrift/
34   compiler/
35     Contains the Thrift compiler, implemented in C++.
37   lib/
38     Contains the Thrift software library implementation, subdivided by
39     language of implementation.
41     cpp/
42     java/
43     php/
44     py/
45     rb/
47   test/
49     Contains sample Thrift files and test code across the target programming
50     languages.
52   tutorial/
54     Contains a basic tutorial that will teach you how to develop software
55     using Thrift.
57 Requirements
58 ============
60 Thrift requires boost shared pointers from boost-1.33.1 or greater, see:
61 http://www.boost.org/libs/smart_ptr/smart_ptr.htm
63 Some portions of Thrift also depend upon libevent, see:
64 http://monkey.org/~provos/libevent/
66 Some portions of Thrift also depend upon zlib, see:
67 http://www.zlib.net/
69 These libraries are open source and may be freely obtained, but they are not
70 provided as a part of this distribution.
72 Resources
73 =========
75 More information about Thrift can be obtained on the Thrift webpage at:
77      http://developers.facebook.com/thrift
79 Acknowledgments
80 ===============
82 Thrift was inspired by pillar, a lightweight RPC tool written by Adam D'Angelo.
84 Installation
85 ============
87 If you are building from the first time out of the source repository, you will
88 need to generate the configure scripts.  (This is not necessary if you
89 downloaded a tarball.)  From the top directory, do:
91         ./bootstrap.sh
93 Once the configure scripts are generated, thrift can be configured.
94 From the top directory, do:
96         ./configure
98 You may need to specify the location of the boost files explicitly.
99 If you installed boost in /usr/local, you would run configure as follows:
101         ./configure --with-boost=/usr/local
103 Note that by default the thrift C++ library is typically built with debugging
104 symbols included. If you want to customize these options you should use the
105 CXXFLAGS option in configure, as such:
107         ./configure CXXFLAGS='-g -O2'
108         ./configure CFLAGS='-g -O2'
109         ./configure CPPFLAGS='-DDEBUG_MY_FEATURE'
111 Run ./configure --help to see other configuration options
113 Please be aware that the Python library will ignore the --prefix option
114 and just install wherever Python's distutils puts it (usually along
115 the lines of /usr/lib/pythonX.Y/site-packages/).  If you need to control
116 where the Python modules are installed, set the PY_PREFIX variable.
117 (DESTDIR is respected for Python and C++.)
119 Make thrift:
121         make
123 From the top directory, become superuser and do:
125         make install
127 Note that some language packages must be installed manually using build tools
128 better suited to those languages (at the time of this writing, this applies
129 to Java, Ruby, PHP).
131 Look for the README file in the lib/<language>/ folder for more details on the
132 installation of each language library package.