Skip to content

Commit 473580d

Browse files
sebmarkbagesebmarkbage
committed
Initial commit
0 parents  commit 473580d

8 files changed

+193
-0
lines changed

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.DS_Store
2+
/build
3+
emsdk
4+
emsdk_portable
5+
*.cmi
6+
*.cmo

‎.gitmodules

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[submodule "ocaml"]
2+
path = ocaml
3+
url = https://github.com/sebmarkbage/ocaml.git
4+
branch = wasmfixes

‎README.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# OCamlrun WebAssembly
2+
3+
This is a build script for building the OCaml bytecode interpreter for WebAssembly using emscripten.
4+
5+
## Why a VM in a VM?
6+
7+
### Why not compile OCaml code straight to WebAssembly?
8+
9+
Currently it is not that easy because AFAIK there is no high fidelity maintained LLVM output target nor any WebAssembly compatible output target. It would also be difficult to do one because WebAssembly currently doesn't have the necessary hooks to scan its stack for GC pointers. Maybe OCaml already maintains a manual stack or can be modified to do so, I don't know.
10+
11+
The interpreter is written in portable C and maintains its own stack so it makes this easy.
12+
13+
However, a big downside of WebAssembly code right now is that VMs implement it as an AOT compilation toolchain. That means that you spend a lot of time upfront compiling code.
14+
15+
If you have a lot of code paths that are not hot, you're wasting a lot more cycles compiling it than it would take to run it in the interpreter. When you run it in the interpreter you can start executing code instantly.
16+
17+
It might be the case that browsers change to an interpreter mode in the future which might change this equation.
18+
19+
### Why not compile OCaml code to JavaScript like js_of_ocaml or BuckleScript?
20+
21+
This is probably still the best technique if you want full GC interop and it gives you JIT capabilities for hot paths.
22+
23+
However, if you have a lot of code that means a lot of JavaScript to parse and compile on the client during start up. The benefit of running a bytecode is that it can immediately start executing.
24+
25+
Additionally, by using the GC built specifically for OCaml, you take advantage of more predictable and consistent GC behavior across browsers.
26+
27+
Multicore OCaml is coming and so is Shared Typed Array Buffers and Atomics for the web. By using a custom memory model we'll be able to take advantage of parallelism in the browser.
28+
29+
## Installation
30+
31+
I have only tried this on OS X so far and haven't polished any build scripts yet.
32+
33+
### 1. Browser
34+
35+
To test this you'll need a browser with WebAssembly enabled such as [Chrome Canary](https://www.google.com/chrome/browser/canary.html).
36+
37+
### 2. Emsdk
38+
39+
First you need to install the Emscripten SDK. According to the [WebAssembly Developer's Guide](http://webassembly.org/getting-started/developers-guide/) you need to currently build the toolchain from source. It says to include `binaryen-master-64bit` but that didn't work for me and currently I don't need it. `sdk-incoming-64bit` should be enough. (Note: This will need a lot of disk space to rebuild clang from source.)
40+
41+
```
42+
git clone https://github.com/juj/emsdk.git
43+
cd emsdk
44+
./emsdk install sdk-incoming-64bit
45+
./emsdk activate sdk-incoming-64bit
46+
```
47+
48+
After these steps, the installation is complete. To enter an Emscripten compiler environment in the current command line prompt, type
49+
50+
```
51+
source ./emsdk_env.sh
52+
```
53+
54+
Return to the project folder.
55+
56+
### 3. Checkout the OCaml source code
57+
58+
The ocaml source is checked out as a Git submodule of this project.
59+
60+
```
61+
git submodule update --init --recursive
62+
```
63+
64+
### 4. Build
65+
66+
In the root of this repo run the build script.
67+
68+
```
69+
./build.sh
70+
```
71+
72+
It will build the example.ml file into OCaml bytecode. This will then be embedded into emscripten's virtual file system.
73+
74+
It will also build the OCaml bytecode interpreter and GC into a Web Assembly file.
75+
76+
`example.html` contains the bootstrapping script.
77+
78+
You can try it out in your browser using `emrun` (or just server it over HTTP yourself).
79+
80+
```
81+
emrun --browser=chrome_canary example.html
82+
```
83+
84+
It should print to the console with the default example.
85+
86+
### Next Steps
87+
88+
This is just the easiest set up to build to get started. However, emscripten and ocamlrun has a lot of features such a virtual file system and dynamic linking that is often not applicable to the web context. We'll want to strip that down into the smallest possible library that can fit neatly into an existing web toolchain.
89+
90+
This script also compiles with the `-O2` flag. We should see if we could cut down of file size with one of the other flags.

‎build.sh

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#!/bin/sh
2+
3+
mkdir -p build
4+
5+
# First we configure and build the native ocaml compiler so that we can use it
6+
# to compile our ml script at the same version.
7+
cd ocaml
8+
make clean
9+
./configure -no-native-compiler -no-debugger -no-curses -no-ocamldoc -no-graph
10+
make world
11+
cd ..
12+
13+
# Build the OCaml example file to byte code.
14+
./ocaml/byterun/ocamlrun ./ocaml/ocamlc -o build/example example.ml -nostdlib -I ./ocaml/stdlib
15+
16+
# Next we configure ocaml for emscripten instead.
17+
cd ocaml
18+
make clean
19+
emconfigure ./configure -cc emcc -no-pthread -no-native-compiler -no-debugger -no-curses -no-ocamldoc -no-graph
20+
21+
# TODO: Fix these aliasing hacks.
22+
# Alias ar to use the llvm version since emscripten requires it but the OCaml
23+
# make files doesn't pick up its override of the standard archive tool.
24+
alias ar='llvm-ar'
25+
26+
## Next we will build the byte code interpreter using emscripten.
27+
cd byterun
28+
emmake make
29+
# internal ranlib command failed try again.
30+
emmake make
31+
32+
# Give the output a file extension so that emscripten can infer it.
33+
mv ocamlrun ocamlrun.o
34+
35+
cd ../..
36+
37+
emcc -s WASM=1 -O2 ocaml/byterun/ocamlrun.o -o build/ocamlrun.js --preload-file build/example

‎example.html

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!doctype html>
2+
<html>
3+
<head>
4+
<title>ocamlrun Web Assembly</title>
5+
<base href="build/">
6+
</head>
7+
<body>
8+
<script src="../example.js"></script>
9+
</body>
10+
</html>

‎example.js

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
var initialTitle = document.title;
2+
3+
var maxDep = 0;
4+
5+
var Module = {
6+
arguments: ['build/example'],
7+
preRun: [],
8+
postRun: [],
9+
print: function(text) {
10+
console.log(text);
11+
},
12+
printErr: function(text) {
13+
console.error(text);
14+
},
15+
setStatus: function(text) {
16+
document.title = initialTitle + (text ? ' - ' + text : '');
17+
},
18+
monitorRunDependencies: function(remaining) {
19+
maxDep = Math.max(maxDep, remaining);
20+
Module.setStatus(remaining ? '' + (maxDep - remaining) + '/' + maxDep + ')' : '');
21+
}
22+
};
23+
Module.setStatus('Downloading...');
24+
window.onerror = function(event) {
25+
Module.setStatus('Exception thrown, see JavaScript console');
26+
Module.setStatus = function(text) {
27+
if (text) Module.printErr('[post-exception status] ' + text);
28+
};
29+
};
30+
31+
var xhr = new XMLHttpRequest();
32+
xhr.open('GET', 'ocamlrun.wasm', true);
33+
xhr.responseType = 'arraybuffer';
34+
xhr.onload = function() {
35+
Module.wasmBinary = xhr.response;
36+
var script = document.createElement('script');
37+
script.src = 'ocamlrun.js';
38+
document.body.appendChild(script);
39+
};
40+
xhr.send(null);

‎example.ml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
let _ = print_string "!!!!!!\n"
2+
let msg = "Hello WebAssembly!"
3+
let _ = print_string msg
4+
let _ = print_newline ()
5+
let _ = print_string "!!!!!!\n"

‎ocaml

Submodule ocaml added at f8764ac

0 commit comments

Comments
 (0)