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

   1 Thrift Haxe Software Library
   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 Using Thrift with Haxe
  24 ========================
  25
  26 Haxe setup
  27 ---------------
  28
  29 Thrift requires Haxe 3.1.3. Installers for Windows and OSX
  30 platforms are available at `http://haxe.org/download`.
  31
  32 Depending on the desired targets, you may have to install the appropriate HaxeLibs
  33 after installing Haxe itself. For example, if you plan to target C#, Java and C++,
  34 enter the following commands after installing Haxe:
  35
  36     haxelib install hxcpp
  37     haxelib install hxjava
  38     haxelib install hxcs
  39
  40 For other targets, please consult the Haxe documentation whether or not any additional
  41 target libraries need to be installed and how to achieve this.
  42
  43
  44 Haxe on Linux
  45 ---------------
  46
  47 For Linux platforms it is recommended to use the distro-specific package
  48 manager, where possible. More detailed information can be found at the
  49 Haxe Linux download section: http://haxe.org/download/linux
  50
  51 If you run into the error message
  52
  53     Uncaught exception - load.c(237) : Failed to load library : /usr/lib/neko/regexp.ndll
  54         (libpcre.so.3: cannot open shared object file: No such file or directory)
  55
  56 this can be solved depending on your OSes bitness by either
  57
  58     sudo ln -sf /usr/lib/libpcre.so.1 /usr/lib/libpcre.so.3
  59     sudo ldconfig
  60
  61 or
  62
  63     sudo ln -sf /usr/lib64/libpcre.so.1 /usr/lib64/libpcre.so.3
  64     sudo ldconfig
  65
  66 Thrift Haxe bindings
  67 -------------------
  68
  69 Thrift Haxe bindings can be set up via the `haxelib` tool
  70 either from the official ASF repo, or via the github mirror.
  71
  72 - To set up any **stable version**, choose the appropriate branch (e.g. `0.12.0`):
  73
  74     - `haxelib git thrift https://github.com/apache/thrift.git 0.12.0 lib/haxe`
  75
  76 - To set up the current **development version**, use the `master` branch:
  77
  78     - `haxelib git thrift https://github.com/apache/thrift.git master lib/haxe`
  79
  80 As usual, the installed library can be updated using `haxelib upgrade`
  81 or `haxelib update thrift`.
  82
  83 In order to work with Thrift, you will need to install the Thrift compiler
  84 or build from source, depending on your operating system. Appropriate
  85 downloads and more information can be found at http://thrift.apache.org
  86
  87 To get started, visit the /tutorial/haxe and /test/haxe dirs for examples.
  88 If you are using HIDE or the FlashDevelop IDE, you'll find appropriate
  89 project files in these folders.
  90
  91
  92 Current status
  93 ========================
  94 - tested with Haxe C++ target
  95 - tested with Haxe PHP target (console/web server, binary protocols)
  96 - transports: Socket, HTTP (servers run inside PHP server/PHP target only), Stream
  97 - protocols: Binary, JSON, Multiplex, Compact
  98 - tutorial client and server available
  99 - cross-test client and server available
 100
 101
 102 Further developments
 103 ========================
 104 - improve to work with C#, Java and JavaScript Haxe/OpenFL targets
 105 - improve to work with more (ideally all) Haxe/OpenFL targets
 106 - add HTTP server, update tutorial and tests accordingly
 107
 108
 109 Known restrictions
 110 ========================
 111
 112 Although designed with maximum portability in mind, for technical reasons some platforms
 113 may only support parts of the library, or not be compatible at all.
 114
 115 Javascript:
 116 - tutorial fails to build because of unsupported Sys.args
 117
 118 PHP HTTP Server notes
 119 ========================
 120
 121 - you have to import PHP files generated by haxe into PHP
 122 ```php
 123 require_once  dirname(__FILE__) . '/bin/php-web-server/Main-debug.php';
 124 ```
 125
 126 - trace() by default outputs into stdout (http response), so you have to redirect it to stderr or you own logs, something like
 127 ```haxe
 128 //remap trace to error log
 129 haxe.Log.trace = function(v:Dynamic, ?infos:haxe.PosInfos)
 130 {
 131         //simulate normal trace https://github.com/HaxeFoundation/haxe/blob/development/std/haxe/Log.hx
 132         var newValue : Dynamic;
 133         if (infos != null && infos.customParams!=null) {
 134                 var extra:String = "";
 135                 for( v in infos.customParams )
 136                         extra += "," + v;
 137                 newValue = v + extra;
 138         }
 139         else {
 140                 newValue = v;
 141         }
 142         var msg = infos != null ? infos.fileName + ':' + infos.lineNumber + ': ' : '';
 143         Sys.stderr().writeString('${msg}${newValue}\n');
 144 }
 145 ```
 146
 147 - to allow thrift server to read/write HTTP request/response, it should be pointed out to php streams
 148 ```haxe
 149 transport =     new TWrappingServerTransport(
 150                                 new TStreamTransport(
 151                                         new TFileStream("php://input", Read),
 152                                         new TFileStream("php://output", Append)
 153                                         )
 154                                 );
 155 ```
 156
 157 - TSimpleServer doesn't stop after first call, so processor.process() should be called instead, or use runOnce property
 158 ```haxe
 159 var server = new TSimpleServer( processor, transport, transfactory, protfactory);
 160 server.runOnce = true;
 161 ```
 162