Thrift Release V0.13.0

Thrift Release v0.13.0

Nov 12, 2019

Contents

1 Download 3 1.1 Release...... 3 1.2 Git Checkout...... 3 1.3 Package Managers...... 3

2 Tutorial 7

3 Developers 9 3.1 Contributing...... 9 3.2 Issue Tracking...... 9 3.3 Source Control...... 9

4 How to Contribute 11 4.1 Github Pull Requests...... 11 4.2 Building Locally...... 12 4.3 Reviewing Open Issues...... 13 4.4 Reporting Bugs...... 13 4.5 Adding a New Language...... 14

5 Coding Standards 17 5.1 General Standards...... 17 5.2 Language Speciﬁc Standards...... 18

6 Mailing Lists & IRC 19 6.1 User Mailing List...... 19 6.2 Developer Mailing List...... 19 6.3 Commits Mailing List...... 19 6.4 IRC...... 20

i ii Thrift, Release v0.13.0

The Apache Thrift software framework, for scalable cross-language services development, combines a software stack with a code generation engine to build services that work efﬁciently and seamlessly between C++, Java, Python, Go, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml and Delphi and other languages.

Contents 1 Thrift, Release v0.13.0

2 Contents CHAPTER 1

Download

1.1 Release

The latest stable release of Thrift is 0.13.0 (released on 2019-OCT-16). • thrift-0.13.0.tar.gz[PGP] | [MD5] • Thrift compiler for Windows (thrift-0.13.0.exe)[PGP] | [MD5] When downloading from a mirror, please be sure to verify the checksums and signature (see the MD5 and PGP links above). The KEYS ﬁle contains the public key(s) used for signing releases.

1.2 Git Checkout

For those who would like to participate in Thrift development, you may checkout Thrift from the GitHub repository. .. code:

$ git clone https://github.com/apache/thrift.git $ cd thrift

We recommend you use our Docker development environment - the same environment the CI builds use.

1.3 Package Managers

Thrift is available in various package managers. • All Languages – Package Manager: Docker – Direct Link: https://hub.docker.com/_/thrift/ – Control File: Dockerﬁle

3 Thrift, Release v0.13.0

– Remarks: Unofﬁcial package. Compiler in /usr/local/bin/thrift • ActionScript – Package Manager: Maven – Direct Link: https://repository.apache.org/#nexus-search;quick~libthrift-as3 – Control File: build.gradle – Maintainers: jking • C++ – Package Manager: Conan – Remarks: Not supported yet, see THRIFT-4800 • C# and .NET Standard – Package Manager: NuGet – Direct Link: https://www.nuget.org/packages/ApacheThrift – Control File: ApacheThrift.nuspec – Maintainers: jfarrell, codesf, jking • D – Package Manager: dub – Direct Link: https://code.dlang.org/packages/apache-thrift – Control File: dub.json – Maintainers: jking • Dart – Package Manager: Pub – Direct Link: https://pub.dartlang.org/packages/thrift – Control File: pubspec.yaml – Maintainers: jking • Erland – Package Manager: Hex PM – Direct Link: https://hex.pm/packages?search=thrift&sort=downloads – Remarks: No ofﬁcial ASF package available • Haskell – Package Manager: Hackage – Direct Link: https://hackage.haskell.org/package/thrift – Control File: thrift.cabal – Maintainers: jfarrell, clavoie, jking • Haxe – Package Manager: Haxelib – Control File: haxelib.json

4 Chapter 1. Download Thrift, Release v0.13.0

– Maintainers: jensg – Remarks: No official ASF package yet, see THRIFT-3036 • Go (golang) – Package Manager: Go modules – Control File: go.mod – Maintainers: dcelasun • Java – Package Manager: Maven – Direct Link: https://repository.apache.org/#nexus-search;quick~org.apache.thrift – Control File: gradle.properties – Maintainers: jking • JavaScript – Package Manager: Bower – Direct Link: https://libraries.io/bower/thrift – Control File: bower.json • Lua – Package Manager: LuaRocks – Direct Link: https://luarocks.org/modules/drauschenbach/thrift – Remarks: No official ASF package yet, see THRIFT-4708 • Node.js – Package Manager: NPM – Direct Link: https://www.npmjs.com/package/thrift – Control File: package.json – Maintainers: wadey, jking • OCaml – Package Manager: opam – Direct Link: https://opam.ocaml.org/packages/thrift/ – Control File: opam – Remarks: No official ASF package yet, see THRIFT-4706 • Perl – Package Manager: CPAN – Direct Link: https://metacpan.org/release/Thrift – Control File: Makefile.PL – Maintainers: jking • PHP – Package Manager: Composer

1.3. Package Managers 5 Thrift, Release v0.13.0

– Direct Link: https://packagist.org/packages/apache/thrift – Control File: composer.json – Maintainers: jfarrell, bufferoverﬂow, jking • Python – Package Manager: PyPi – Direct Link: https://pypi.python.org/pypi/thrift – Control File: setup.py – Maintainers: jfarrell – Remarks: Outdated, see THRIFT-4687 • Ruby – Package Manager: Ruby Gem – Direct Link: https://rubygems.org/gems/thrift – Control File: thrift.gemspec – Maintainers: jfarrell – Remarks: Outdated, see THRIFT-4707 • Rust – Package Manager: Cargo – Direct Link: https://crates.io/crates/thrift – Control File: cargo.toml – Maintainers: allengeorge, jfarrell • Common LISP, Smalltalk and Swift – Remarks: No ofﬁcial ASF package available for these languages.

6 Chapter 1. Download CHAPTER 2

Tutorial

Install Apache Thrift Many Linux distributions have Apache Thrift packaged in their repositories and these packages should be preferred. MacOS users can use package managers like Homebrew to install Thrift. Windows users can download the compiler from our download page. Manual Installation Alternatively, you can build Thrift from source. Follow our building from source guide. Writing a .thrift file After the compiler is installed you will need to create a .thrift file. This file is an interface definition made up of Thrift types and Services. The services you define in this file are implemented by the server and are called by any clients. In this tutorial, we’ll be using tutorial.thrift and shared.thrift. Generate Source Code The Thrift compiler is used to compile your Thrift file into source code used by your server code and client libraries. thrift--gen tutorial.thrift

To recursively compile all ﬁles imported by a Thrift ﬁle, run: thrift-r--gen tutorial.thrift

The sample tutorial.thrift file defines a basic calculator service, which includes another file called shared.thrift. Both files will be used to demonstrate how to build a Thrift client and server pair. Language specific implementations of this tutorial can be found on Github.

7 Thrift, Release v0.13.0

8 Chapter 2. Tutorial CHAPTER 3

Developers

3.1 Contributing

Anyone interested in contributing to Apache Thrift should read the How to Contribute guide prior to submitting any patches to Jira. There’s also a short guide on how to add new language bindings. If you have any questions about this please contact us.

3.2 Issue Tracking

Apache Thrift tracks both bugs and enhancements using Jira. Before ﬁling new requests, we ask that you ﬁrst do the following: • Search the Jira database • Check the user mailing list via searching the archives or asking a question

3.3 Source Control

The Apache Thrift source code resides in Github. Three types of access are available: • Web access (read-only) Source code can be browsed via the Web: https://github.com/apache/thrift • Anonymous (read-only) git git clone https://github.com/apache/thrift.git

• Committer Access (read+write) First, follow these instructions to link your Apache account to your Github account.

9 Thrift, Release v0.13.0

git clone [email protected]:apache/thrift.git

10 Chapter 3. Developers CHAPTER 4

How to Contribute

Thank you for your interest in contributing to the Apache Thrift project! Information on why and how to contribute is available on the Apache Software Foundation (ASF) web site. In particular, we recommend the following to become acquainted with Apache Contributions: • Contributors Tech Guide • Get Involved • Legal aspects on submission of contributions

4.1 Github Pull Requests

This is the preferred method of submitting changes. When you submit a pull request through github, it activates the continuous integration (CI) build systems at Appveyor and Travis to build your changesxi on a variety of Linux and Windows configurations and run all the test suites. Follow these requirements for a successful pull request: • All significant changes require a Jira Ticket. Trivial changes such as fixing a typo or a compiler warning do not. • All pull requests should contain a single commit per issue, or we will ask you to squash it. • The pull request title must begin with the Jira ticket identifier if it has an associated ticket, for example:

THRIFT-9999: an example pull request title

• Commit messages must follow this pattern for code changes (deviations will not be merged):

THRIFT-9999: [summary of fix, one line if possible] Client: [language(s) affected, comma separated, for example:"cpp,erl,perl"]

Instructions: 1. Fork the repository. 2. Clone the fork to your development system. 3. Create a branch for your changes (best practice is issue as branch name, e.g. THRIFT-9999).

11 Thrift, Release v0.13.0

4. Modify the source to include the improvement/bugﬁx, and: 1. Remember to provide tests for all submitted changes! 2. Use test-driven development (TDD): add a test that will isolate the bug before applying the change that ﬁxes it. 3. Verify that you follow Thrift Coding Standards (you can run make style, which ensures proper format for some languages). 4. [optional] Verify that your change works on other platforms by adding a GitHub service hook to Travis CI and AppVeyor. You can use this technique to run the Thrift CI jobs in your account to check your changes before they are made public. Every GitHub pull request into Thrift will run the full CI build and test suite on your changes. 5. Squash your changes to a single commit. This maintains clean change history. 6. Commit and push changes to your branch (please use issue name and description as commit title, e.g. “THRIFT- 9999: make it perfect”), with the affected languages on the next line of the description. 7. Use GitHub to create a pull request going from your branch to apache:master. Ensure that the Jira ticket number is at the beginning of the title of your pull request, same as the commit title. 8. Wait for other contributors or committers to review your new addition, and for a CI build to complete. 9. Wait for a committer to commit your patch. You can nudge the committers if necessary by sending a message to the developer mailing list.

4.2 Building Locally

For Windows systems, see our detailed instructions on the CMake README. For Windows Native C++ builds, see our Appveyor batch ﬁles. For Docker, see our detailed instructions on the Docker README.

4.2.1 Building from Source

If you are building from the ﬁrst time out of the source repository, you will need to generate the conﬁgure scripts. (This is not necessary if you downloaded a released tarball.) From the top directory, do:

./bootstrap.sh

Once the conﬁgure scripts are generated, thrift can be conﬁgured. From the top directory, do:

./configure

Disable languages for which you don’t want to generate a library. This does not include the code generator:

./configure--without-java

You may need to specify the location of the boost ﬁles explicitly. If you installed boost in /usr/local, you would run conﬁgure as follows:

./configure-- with-boost=/usr/local

If you want to override the automatic Java SDK detection, use the JAVAC environment variable:

12 Chapter 4. How to Contribute Thrift, Release v0.13.0

./configure JAVAC=/usb/bin/javac

Note that by default the Thrift C++ library is built with debugging symbols included. If you want to customize these options you should use the CXXFLAGS option in conﬁgure:

./configure CXXFLAGS='-g -O2' ./configure CFLAGS='-g -O2' ./configure CPPFLAGS='-DDEBUG_MY_FEATURE'

To see other conﬁguration options run:

./configure--help

Once conﬁgured, you can build Thrift with make: make and run the test suite: make check and the cross language test suite: sh test/test.sh

Finally, to install the generated binary become root and do: make install

Note that some language packages must be installed manually using build tools better suited to those languages (Java, Ruby, PHP etc). Look for the README ﬁle in the lib// folder for more details on the installation of each language library package.

4.3 Reviewing Open Issues

If you’d like to help by doing reviews, you have two options: • Review the Pull Request backlog on Github. Code reviews are open to all. • Review the Jira issue tracker. You can search for tickets relating to languages you are interested in or currently using with thrift, for example a Jira search (Issues -> Search For Issues) query of project = THRIFT AND component in ("Erlang - Library") and status not in (resolved, closed) will locate all open Erlang Library issues.

4.4 Reporting Bugs

• Check if the issue is already in the Jira issue tracker. • If not, create a ticket describing the problem.

4.3. Reviewing Open Issues 13 Thrift, Release v0.13.0

4.5 Adding a New Language

When considering new language bindings, there are certain points to think about. First, you should find out if you are about to implement completely new language bindings that are not yet supported with Thrift, or if you just want to add support for a specific “flavour” of an already implemented language. If bindings for a language exist, but are incomplete / missing support for a feature, it is recommended to add the new feature as an option to the existing language. For a good model on how to do this take look at the js/nodejs implementations, or the various options that already exist for Python. thrift --help is a good point to start. Depending on the amount of changes necessary, you will still find the rest of the document useful.

4.5.1 Preparation

The good news is, although there is some work required, the process is not as hard as it looks. First, make sure you have a fully functional build environment and are able to build the compiler from source. Next, search Jira and maybe the mailing list archives. If you do not ﬁnd anything similar, create a new ticket, shortly describing what you are planning. If you are not quite sure, ask on the developers mailing list. Now fork and clone the repository from Github and switch to a new branch for development.

4.5.2 Minimal Feature Set

• Implement the code generator, typically by picking one from the existing pool that is close to what you need. There are already plenty of languages supported, and you’ll ﬁnd OOP, procedural and functional styles. If you are not sure which one to choose, head to the next point. • Implement the Thrift library for that particular language, again by picking one of the existing libraries as a starting point. Because the libraries differ largely with regard to the depth/featureset of their implementations it is recommended to have a closer look on what is implemented, and what is not. • Implement the standardized Thrift cross platform test and make sure all tests succeed when run against at least one other language. This ensures interoperability and makes sure that the code does not only work when talking to itself (= same language). You may also add other tests, but these should be put into lib/yourlang/test rather than test/yourlang - the latter is intended to host solely the cross language tests. • Implement the tutorial code and test it against another language. If you did everything well, this last step is relatively easy. The minimum required feature set should cover at least: • Transports: Sockets, Buffered, Framed required, HTTP client recommended • Protocols: Binary and Multiplex required, JSON recommended • Server types: SimpleServer required

4.5.3 Recommended Features

These are not strictly required in the ﬁrst run, but are commonly used. Depending on the language, some things may be easier to implement than others. Alternatively, consider adding the features listed below later as additional contributions instead of trying to press them into the initial contribution. If in doubt, focus on quality rather than quantity. • Transports: HTTP server, Pipes, NamedPipes (where it makes sense) • Protocols: Compact

14 Chapter 4. How to Contribute Thrift, Release v0.13.0

• Server types: Nonblocking, Threaded and/or Threadpool server implementation

4.5.4 Final Steps

• Add a README.md file to your library’s folder, describing requirements, dependencies and whatever else might be important. Look at the existing readme files if you aren’t sure. • Make sure the generator, library, tests and tutorial have proper makefile.am files. Include everything into the build/test scripts. If you need help with these steps, don’t hesitate to ask on the mailing lists. • All done! Open a pull request with your changes.

4.5.5 Notes

These steps are not a linear process, but an iterative one. Even if the code that comes out of the generator compiles, doesn’t spit out any warnings and seemingly runs ﬁne, you’ll still run into problems as you work on implementing the library and tests. This is normal and expected. It’s a good idea to create the JIRA ticket and post your work early. This serves not only as announcement, but also provides a good starting point for other people who might be looking for that feature. You’ll be able to get valuable early feedback and get support with implementation and testing. Having someone else look over your code is a good thing and will ensure high code quality. Happy coding!

4.5. Adding a New Language 15 Thrift, Release v0.13.0

16 Chapter 4. How to Contribute CHAPTER 5

Coding Standards

Anyone can write code that a computer can understand. Good programmers write code that humans can understand. – Martin Fowler, 1999 The purpose of this document is to make everyone’s life easier. It’s easier when you read good, well formatted code with a clearly deﬁned purpose. The only way to read clean code is to write clean code. This document can help you achieve that, but keep in mind that nothing in this list is a silver bullet. Simply, focus on readability and imagine reading your own code ten years from now.

5.1 General Standards

Thrift has a long history and not all existing code follows these rules, but we still want to improve the codebase over time. When making small changes do not refactor whole files as it makes the commit unreadable. If you are working on something larger, follow these rules as best you can. When in doubt - reach out to other developers. Code review is the best way to improve readability. • Use spaces not tabs • Use only ASCII characters in file and directory names • Use Unix-style line endings (LF) (on Windows use git config core.autocrlf true) • Stick to maximum 100 characters per line • If not specified otherwise in a language specific standard, use 2 spaces for indentation • Each file must start with a comment containing the Apache License • Public API of libraries should be documented, preferably using a format native to that language (Javadoc, Doxygen etc.)

17 Thrift, Release v0.13.0

5.2 Language Speciﬁc Standards

Some languages might have their own standards, see lib/LANG/coding_standards.md.

18 Chapter 5. Coding Standards CHAPTER 6

Mailing Lists & IRC

In accordance with the principles of the Apache Software Foundation, Thrift encourages a collaborative and community-based development environment. All project discussion is carried out publicly, on the following archived lists.

6.1 User Mailing List

If you use Apache Thrift, please subscribe to the Thrift user mailing list. This list is for questions about Thrift and announcements from the team relevant to all users. Subscribe| Unsubscribe| View Archives| View Archives (Incubator)

6.2 Developer Mailing List

If you would like to contribute to Apache Thrift, subscribe to the Thrift developer mailing list. Subscribe| Unsubscribe| View Archives| View Archives (Incubator)

6.3 Commits Mailing List

This list receives notiﬁcations about all code changes made to Apache Thrift. Subscribe| Unsubscribe| View Archives| View Archives (Incubator)

Note: subscription is required to post to all lists.

19 Thrift, Release v0.13.0

6.4 IRC

Many of the Apache Thrift developers and community members hang out in the #thrift channel on irc.freenode.net. If you are new to IRC, you can use a client such as xchat or Irssi or a web-based client.

20 Chapter 6. Mailing Lists & IRC