1 | Apache Thrift
|
2 | =============
|
3 |
|
4 | Introduction
|
5 | ============
|
6 |
|
7 | Thrift is a lightweight, language-independent software stack for
|
8 | point-to-point RPC implementation.
|
9 | Thrift provides clean abstractions and implementations for data transport,
|
10 | data serialization, and application level processing. The code generation
|
11 | system takes a simple definition language as input and generates code
|
12 | across programming languages that uses the abstracted stack to build
|
13 | interoperable RPC clients and servers.
|
14 |
|
15 | ![Apache Thrift Layered Architecture](doc/images/thrift-layers.png)
|
16 |
|
17 | Thrift makes it easy for programs written in different programming
|
18 | languages to share data and call remote procedures. With support
|
19 | for [28 programming languages](LANGUAGES.md), chances are Thrift
|
20 | supports the languages that you currently use.
|
21 |
|
22 | Thrift is specifically designed to support non-atomic version changes
|
23 | across client and server code. This allows you to upgrade your
|
24 | server while still being able to service older clients; or have newer
|
25 | clients issue requests to older servers. An excellent community-provided
|
26 | write-up about thrift and compatibility when versioning an API can be
|
27 | found in the [Thrift Missing Guide](https://diwakergupta.github.io/thrift-missing-guide/#_versioning_compatibility).
|
28 |
|
29 | For more details on Thrift's design and implementation, see the Thrift
|
30 | whitepaper included in this distribution, or at the README.md file
|
31 | in your particular subdirectory of interest.
|
32 |
|
33 | Status
|
34 | ======
|
35 |
|
36 | | Branch | Travis | Appveyor | Coverity Scan | codecov.io | Website |
|
37 | | :----- | :----- | :------- | :------------ | :--------- | :------ |
|
38 | | [`master`](https://github.com/apache/thrift/tree/master) | [![Build Status](https://travis-ci.org/apache/thrift.svg?branch=master)](https://travis-ci.org/apache/thrift/branches) | [![Build status](https://ci.appveyor.com/api/projects/status/github/apache/thrift?branch=master&svg=true)](https://ci.appveyor.com/project/ApacheSoftwareFoundation/thrift/history) | [![Coverity Scan Build Status](https://scan.coverity.com/projects/1345/badge.svg)](https://scan.coverity.com/projects/thrift) | | [![Website](https://img.shields.io/badge/official-website-brightgreen.svg)](https://thrift.apache.org/) |
|
39 | | [`0.13.0`](https://github.com/apache/thrift/tree/0.13.0) | [![Build Status](https://travis-ci.org/apache/thrift.svg?branch=0.13.0)](https://travis-ci.org/apache/thrift/branches) | | | | |
|
40 | | [`0.12.0`](https://github.com/apache/thrift/tree/0.12.0) | [![Build Status](https://travis-ci.org/apache/thrift.svg?branch=0.12.0)](https://travis-ci.org/apache/thrift/branches) | | | | |
|
41 |
|
42 | Releases
|
43 | ========
|
44 |
|
45 | Thrift does not maintain a specific release calendar at this time.
|
46 |
|
47 | We strive to release twice yearly. Download the [current release](http://thrift.apache.org/download).
|
48 |
|
49 | License
|
50 | =======
|
51 |
|
52 | Licensed to the Apache Software Foundation (ASF) under one
|
53 | or more contributor license agreements. See the NOTICE file
|
54 | distributed with this work for additional information
|
55 | regarding copyright ownership. The ASF licenses this file
|
56 | to you under the Apache License, Version 2.0 (the
|
57 | "License"); you may not use this file except in compliance
|
58 | with the License. You may obtain a copy of the License at
|
59 |
|
60 | http://www.apache.org/licenses/LICENSE-2.0
|
61 |
|
62 | Unless required by applicable law or agreed to in writing,
|
63 | software distributed under the License is distributed on an
|
64 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
65 | KIND, either express or implied. See the License for the
|
66 | specific language governing permissions and limitations
|
67 | under the License.
|
68 |
|
69 | Project Hierarchy
|
70 | =================
|
71 |
|
72 | thrift/
|
73 |
|
74 | compiler/
|
75 |
|
76 | Contains the Thrift compiler, implemented in C++.
|
77 |
|
78 | lib/
|
79 |
|
80 | Contains the Thrift software library implementation, subdivided by
|
81 | language of implementation.
|
82 |
|
83 | cpp/
|
84 | go/
|
85 | java/
|
86 | php/
|
87 | py/
|
88 | rb/
|
89 | ...
|
90 |
|
91 | test/
|
92 |
|
93 | Contains sample Thrift files and test code across the target programming
|
94 | languages.
|
95 |
|
96 | tutorial/
|
97 |
|
98 | Contains a basic tutorial that will teach you how to develop software
|
99 | using Thrift.
|
100 |
|
101 | Development
|
102 | ===========
|
103 |
|
104 | To build the same way Travis CI builds the project you should use docker.
|
105 | We have [comprehensive building instructions for docker](build/docker/README.md).
|
106 |
|
107 | Requirements
|
108 | ============
|
109 |
|
110 | See http://thrift.apache.org/docs/install for a list of build requirements (may be stale). Alternatively, see the docker build environments for a list of prerequisites.
|
111 |
|
112 | Resources
|
113 | =========
|
114 |
|
115 | More information about Thrift can be obtained on the Thrift webpage at:
|
116 |
|
117 | http://thrift.apache.org
|
118 |
|
119 | Acknowledgments
|
120 | ===============
|
121 |
|
122 | Thrift was inspired by pillar, a lightweight RPC tool written by Adam D'Angelo,
|
123 | and also by Google's protocol buffers.
|
124 |
|
125 | Installation
|
126 | ============
|
127 |
|
128 | If you are building from the first time out of the source repository, you will
|
129 | need to generate the configure scripts. (This is not necessary if you
|
130 | downloaded a tarball.) From the top directory, do:
|
131 |
|
132 | ./bootstrap.sh
|
133 |
|
134 | Once the configure scripts are generated, thrift can be configured.
|
135 | From the top directory, do:
|
136 |
|
137 | ./configure
|
138 |
|
139 | You may need to specify the location of the boost files explicitly.
|
140 | If you installed boost in `/usr/local`, you would run configure as follows:
|
141 |
|
142 | ./configure --with-boost=/usr/local
|
143 |
|
144 | Note that by default the thrift C++ library is typically built with debugging
|
145 | symbols included. If you want to customize these options you should use the
|
146 | CXXFLAGS option in configure, as such:
|
147 |
|
148 | ./configure CXXFLAGS='-g -O2'
|
149 | ./configure CFLAGS='-g -O2'
|
150 | ./configure CPPFLAGS='-DDEBUG_MY_FEATURE'
|
151 |
|
152 | To enable gcov required options -fprofile-arcs -ftest-coverage enable them:
|
153 |
|
154 | ./configure --enable-coverage
|
155 |
|
156 | Run ./configure --help to see other configuration options
|
157 |
|
158 | Please be aware that the Python library will ignore the --prefix option
|
159 | and just install wherever Python's distutils puts it (usually along
|
160 | the lines of `/usr/lib/pythonX.Y/site-packages/`). If you need to control
|
161 | where the Python modules are installed, set the PY_PREFIX variable.
|
162 | (DESTDIR is respected for Python and C++.)
|
163 |
|
164 | Make thrift:
|
165 |
|
166 | make
|
167 |
|
168 | From the top directory, become superuser and do:
|
169 |
|
170 | make install
|
171 |
|
172 | Uninstall thrift:
|
173 |
|
174 | make uninstall
|
175 |
|
176 | Note that some language packages must be installed manually using build tools
|
177 | better suited to those languages (at the time of this writing, this applies
|
178 | to Java, Ruby, PHP).
|
179 |
|
180 | Look for the README.md file in the lib/<language>/ folder for more details on the
|
181 | installation of each language library package.
|
182 |
|
183 | Package Managers
|
184 | ================
|
185 |
|
186 | Apache Thrift is available via a number of package managers, a list which is
|
187 | is steadily growing. A more detailed overview can be found
|
188 | [at the Apache Thrift web site under "Libraries"](http://thrift.apache.org/lib/)
|
189 | and/or in the respective READMEs for each language under /lib
|
190 |
|
191 | Testing
|
192 | =======
|
193 |
|
194 | There are a large number of client library tests that can all be run
|
195 | from the top-level directory.
|
196 |
|
197 | make -k check
|
198 |
|
199 | This will make all of the libraries (as necessary), and run through
|
200 | the unit tests defined in each of the client libraries. If a single
|
201 | language fails, the make check will continue on and provide a synopsis
|
202 | at the end.
|
203 |
|
204 | To run the cross-language test suite, please run:
|
205 |
|
206 | make cross
|
207 |
|
208 | This will run a set of tests that use different language clients and
|
209 | servers.
|
210 |
|
211 |
|