initial export

Author: Hongbo Zhang

.gitignore

@@ -0,0 +1,52 @@
+*~
+_build
+*.compile
+*.native
+*.byte
+*.cmo
+*.annot
+*.cmi
+*.cmx
+jslambda
+
+exports.js
+*.lambda
+*.rawlambda
+node_modules
+*.o
+*.lam
+err.log
+.idea
+ocaml_pack
+*.0.js
+*~
+stdlib/c.js
+*.map
+*.zip
+*.gz
+*#
+qcc/
+.#*
+# jscomp/stdlib/external/*.js
+oxml
+*.cmj
+ocamlscript
+*.rawlambda
+*.lambda
+ocaml/*.js
+ocaml/*/*/*.js
+ocaml/*.js
+
+jscomp/stdlib/.depend
+jscomp/test_cases/.depend
+test.sh
+test.json
+ocaml/bin
+ocaml/lib
+ocaml/man
+*~
+*.annot
+*.mj
+jscomp/bench/*.js
+*.bak
+.vscode

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ocaml"]
+	path = ocaml
+	url = ./ocaml

LICENSE

@@ -0,0 +1,312 @@
+# OCamlScript
+
+## Introduction
+OCamlScript is a Javascript backend for [the OCaml language](https://ocaml.org/)
+which aims to provide a better language for the Javascript platform.
+
+One OCaml module is mapped to one JS module, and no name mangling happens
+so that:
+
+1. The stacktrace is preserved, the generated code is debuggable.
+2. You can call `List.length` (List is a module in OCaml standard library)
+   in a plain Javascript file.
+
+
+### A simple example
+
+``` ocaml
+let sum n =
+    let v  = ref 0 in
+    for i = 0 to n do
+       v := !v + i
+    done;
+    !v
+```
+
+Generated code under is as below:
+
+``` js
+function sum(n) {
+  var v = 0;
+  for(var i = 0; i<= n; ++i){
+    v += i;
+  }
+  return v;
+}
+```
+
+As you can see, there is no name mangling in the generated code, so suppose the
+module is called `M`, you can call `M.fib` in vanilla Javascript
+
+You can play the online [in-browser compiler](http://zhanghongbo.me/js-demo).
+
+
+  
+# Disclaimer
+
+This project is currently released to exchange ideas outside
+Bloomberg and collect some early feedback from OCaml and Javascript community,
+it is in an *very early* stage and not production ready
+for your own projects *yet*.
+
+
+## Build
+
+Note that you have to clone this project with `--recursive` option, we can only distribute
+the patch of OCaml due to License restrictions.
+
+
+### Linux and Mac OS 
+
+
+1. Apply the patch to OCaml compiler and build
+
+  Please ignore the warnings generated by git apply
+  
+  ```
+  cd ocaml
+  git apply ../js.diff
+  ./configure -prefix `pwd`
+  make world.opt
+  make install
+  ```
+2. Build OcamlScript Compiler
+
+  Assume that you have ocamlopt.opt in the PATH
+  ```
+  cd ../jscomp
+  ocamlopt.opt -I +compiler-libs -I bin -c bin/compiler.mli bin/compiler.ml
+  ocamlopt.opt -g -linkall -o bin/ocamlscript -I +compiler-libs ocamlcommon.cmxa ocamlbytecomp.cmxa  bin/compiler.cmx main.cmx
+  ```
+  Now you have a binary called `ocamlscript` under `jscomp` directory,
+  put it in your `PATH`
+  
+3. Build the runtime with `ocamlscript`
+
+  ```sh
+  cd runtime
+  make all
+  ```
+
+4. Build the standard library with `ocamlscript`
+
+  ```sh
+  cd ../stdlib
+  make all 
+  ```
+5. Test 
+
+  We first create a file called `hello.ml`:
+
+  ```sh
+  mkdir tmp  # create tmp directory inside the stdlib
+  cd tmp 
+  echo 'print_endline "hello world";;' >hello.ml
+  ```
+  Then we compiled it with `ocamlscript`
+  ```sh
+  OCAML_RAW_JS=1 ocamlscript -I . -I ../ -c hello.ml
+  ```
+  
+  It should generate a file called `hello.js`, then we runt the `js` file
+
+  ```sh
+  node hello.js
+  ```
+  If everything goes well, you will see `hello world` on your screen.
+
+
+
+
+# Licensing 
+
+The [OCaml](./ocaml) directory is a submodule from OCaml's official repo(4.02.3), all its rights
+are reserved by [INRIA](http://www.inria.fr/) (see its QPL LICENSE for more details).
+
+Our compiler relies on a patch  [(js.diff)](./js.diff) to the OCaml compiler.
+
+This project reused and adapted part of [js_of_ocaml](https://github.com/ocsigen/js_of_ocaml)'s:
+* Some small printing utilties in [pretty printer](./jscomp/js_dump.ml).
+* Part of the [Javascript runtime](./jscomp/runtime) support
+
+It adapted two modules [jscomp/lam_pass_exits.ml] and
+[jscomp/lam_pass_lets_dce] from OCaml's [bytecomp/simplif], the main
+reasons are those optimizations are not optimal for Javascript
+backend.
+
+[jscomp/js_main.ml] is adapted from [driver/main], it is not actually
+used, since currently we make this JS backend as a plugin instead, but
+it shows that it is easy to assemble a whole compler using OCaml
+compiler libraries and upon that we can add more compilation flags for
+JS backend.
+
+[jscomp/stdlib] is copied from [ocaml/stdlib] to have it compiled with
+the new JS compiler.
+
+Since our work is derivative work, we choose the GPL v2 license to
+make it compatible with
+[js_of_ocaml](http://ocsigen.org/js_of_ocaml/).
+
+Note that QPL license is not compatible with GPL V2, so we distribute
+our changes to the compiler as a patch instead.
+
+## Design goal
+
+1. Readability 
+ 1.   No name mangling
+ 2.   Support Javascript modules systems
+ 3.   Integrate with existing javascript ecosystem, for example,
+      [npm](https://www.npmjs.com/), [webpack](https://github.com/webpack).
+ 4.   Straight-forward FFI, generate tds file to target [Typescript](http://www.typescriptlang.org/) for better tooling
+ 
+2. Separate and *extremely fast* compilation.
+
+3. Better performance than hand-written Javascript:
+   thanks to a sound type system in OCaml so that we
+   can play more optimizations and pipe it to Google Closure Compiler
+   for production mode.
+
+4. Smaller code than hand written JS code, compatible with Google Closure Compiler
+
+5. Support NodeJs, Web Browser and various Javascript target platform.
+
+6. Compatible with OCaml semantics modulo c-bindings and Obj, Marshal module
+
+## More examples
+
+### NodeJS support
+
+Below it is an idea how it would integrate with the existing JS
+eco-system:
+
+```js
+
+var $$Array = require('./array'); // OCaml Array module
+var List = require ('./list'); // OCaml List module
+
+List.iter(function(x){console.log('hi, nodejs '+x)},
+    $$Array.to_list ($$Array.init(5,function(x){return x})))
+```
+
+You get the output:
+
+```sh
+hi, nodejs 0
+hi, nodejs 1
+hi, nodejs 2
+hi, nodejs 3
+hi, nodejs 4
+```
+
+### A naive benchmark with Facebook immutable
+
+
+Below is a *contrived* example to demonstrate our motivation,
+it tries to insert 1000,000 keys to an immutable map and query it
+
+```Ocaml
+module IntMap = Map.Make(struct
+  type t = int
+  let compare (x : int) y = compare x y
+  end)
+
+let test () =
+  let m = ref IntMap.empty in
+  let count = 1000000 in
+  for i = 0 to count do
+    m := IntMap.add i i !m
+  done;
+  for i = 0 to count  do
+    ignore (IntMap.find i !m )
+  done
+
+let () = test()
+
+```
+
+This is an equivalent JS version by using Facebook's
+[immutable](http://facebook.github.io/immutable-js/) library
+
+
+``` js
+'use strict';
+var Immutable = require('immutable');
+var Map = Immutable.Map;
+var m = new Map();
+var test  = function(){
+    var count  = 1000000
+    for(var i = 0; i < count; ++i){
+        m = m.set(i, i );
+    }
+    for(var j = 0; j < count ; ++j){
+        m.get(j)
+    }
+}
+
+test ()
+```
+
+Runtime performance:
+- OCaml Immutable Map:  1186ms
+- Facebook Immutable Map: 3415ms
+
+Code Size:
+- OCaml (Prod mode): 899 Bytes
+- Facebook Immutable : 55.3K Bytes
+
+
+## Status
+
+
+It covers the most of  OCaml language, given that it is a quite young
+project (5 men-months until Jan 2016), there are still plenty of work
+to be done.
+
+Some known issues are listed as below:
+
+1. Language features:
+
+   Recursive modules, have not looked into it yet.
+   
+   Better Currying support. Currently, we have an inference engine for
+   function curring and we do cross module inference, however, there
+   are some more challenging cases, for example, high order functions,
+   it can be resolved by either aggressive inlining or fall back to a
+   slow path using `Function.prototype.length`. We prepared the
+   runtime support in [module curry](jscomp/runtime/curry.ml), will support it in the near
+   future.
+
+   Int32 operations, currently, Int use Float operations, this should
+   be fixed in the near future.
+   
+2. Standard libraries distributed with OCaml:
+
+   IO support, we have very limited support for
+   `Pervasives.print_endline` and `Pervasives.prerr_endline`, it's
+   non-trivial to preserve the same semantics of IO between OCaml and
+   NodeJS, one solution is to functorize all IO operations. Functors
+   are then inlined so there will no be performance cost or code size
+   penalty.
+
+   Bigarray, Unix, Num, Int64
+
+## License
+
+The OCaml to JS compiler libraries are distributed under the GPL (version 2.0);
+see the LICENSE file at the top of the source tree for more information.
+
+
+The contents of some files in this distribution was derived from external
+sources with different licenses.  The original copyright and license
+notice was preserved in the affected files.
+
+## Question, Comments and Feedback
+
+If you have questions, comments, suggestions for improvement or any other inquiries
+regarding this project, feel free to open an issue in the issue tracker.
+
+
+
+
+
+