README.md
1Haskell Thrift Bindings
2
3License
4=======
5
6Licensed to the Apache Software Foundation (ASF) under one
7or more contributor license agreements. See the NOTICE file
8distributed with this work for additional information
9regarding copyright ownership. The ASF licenses this file
10to you under the Apache License, Version 2.0 (the
11"License"); you may not use this file except in compliance
12with the License. You may obtain a copy of the License at
13
14 http://www.apache.org/licenses/LICENSE-2.0
15
16Unless required by applicable law or agreed to in writing,
17software distributed under the License is distributed on an
18"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19KIND, either express or implied. See the License for the
20specific language governing permissions and limitations
21under the License.
22
23Compile
24=======
25
26Use Cabal to compile and install; ./configure uses Cabal underneath, and that
27path is not yet well tested. Thrift's library and generated code should compile
28with pretty much any GHC extensions or warnings you enable (or disable).
29Please report this not being the case as a bug on
30https://issues.apache.org/jira/secure/CreateIssue!default.jspa
31
32Chances you'll need to muck a bit with Cabal flags to install Thrift:
33
34CABAL_CONFIGURE_FLAGS="--user" ./configure
35
36Base Types
37==========
38
39The mapping from Thrift types to Haskell's is:
40
41 * double -> Double
42 * byte -> Data.Int.Int8
43 * i16 -> Data.Int.Int16
44 * i32 -> Data.Int.Int32
45 * i64 -> Data.Int.Int64
46 * string -> Text
47 * binary -> Data.ByteString.Lazy
48 * bool -> Boolean
49
50Enums
51=====
52
53Become Haskell 'data' types. Use fromEnum to get out the int value.
54
55Lists
56=====
57
58Become Data.Vector.Vector from the vector package.
59
60Maps and Sets
61=============
62
63Become Data.HashMap.Strict.Map and Data.HashSet.Set from the
64unordered-containers package.
65
66Structs
67=======
68
69Become records. Field labels are ugly, of the form f_STRUCTNAME_FIELDNAME. All
70fields are Maybe types.
71
72Exceptions
73==========
74
75Identical to structs. Use them with throw and catch from Control.Exception.
76
77Client
78======
79
80Just a bunch of functions. You may have to import a bunch of client files to
81deal with inheritance.
82
83Interface
84=========
85
86You should only have to import the last one in the chain of inheritors. To make
87an interface, declare a label:
88
89 data MyIface = MyIface
90
91and then declare it an instance of each iface class, starting with the superest
92class and proceeding down (all the while defining the methods). Then pass your
93label to process as the handler.
94
95Processor
96=========
97
98Just a function that takes a handler label, protocols. It calls the
99superclasses process if there is a superclass.
100
101Releasing to Hackage
102====================
103
104Using the [Docker Container for Ubuntu Bionic](../../build/docker/README.md), run:
105
106 root@e941f5311545:/thrift/src# ./bootstrap.sh && ./configure
107 root@e941f5311545:/thrift/src# cd lib/hs && make dist-local
108
109This will produce a `lib/hs/dist/thrift-<version>.tar.gz` file. Take this
110file and upload it as a Haskell Hackage
111[package candidate](https://hackage.haskell.org/upload#candidates) and
112check to make sure all the information is correct. Assuming all is satisfactory,
113you can upload the package as official using the link at the top of the page.
114