ceph/src/jaegertracing/thrift/lib/hs/README.md

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