sdks/wasm/README.md

   1 ## Contents
   2 - **bcl** directory: Core libraries to be used with the runtime.
   3 - **driver.c**, **libmonosgen-2.0.a**, **library_mono.js**: Source / Binaries for custom building the runtime. See compilation instructions down.
   4 - **debug**, **release** directories: Pre-compiled runtimes using the above driver in release and debug configurations.
   5 - **sample.html**, **sample.cs**: Sample code, see sample details below.
   6
   7
   8 ## Compiling mono
   9
  10 Mono requires the latest [emscripten][1] installed and built. Emscripten is *not* required if simply using the sample.
  11 The pre-built binaries are compiled using the following command line for the debug build:
  12
  13 ```
  14 emcc -g4 -Os -s WASM=1 -s ALLOW_MEMORY_GROWTH=1 -s BINARYEN=1 -s "BINARYEN_TRAP_MODE='clamp'" -s TOTAL_MEMORY=134217728 -s ALIASING_FUNCTION_POINTERS=0 -s ASSERTIONS=2 --js-library library_mono.js driver.o $(TOP)/sdks/out/wasm-interp/lib/libmonosgen-2.0.a -o debug/mono.js -s NO_EXIT_RUNTIME=1 -s "EXTRA_EXPORTED_RUNTIME_METHODS=['ccall', 'FS_createPath', 'FS_createDataFile', 'cwrap', 'setValue', 'getValue', 'UTF8ToString']"
  15 ```
  16
  17 ## Sample
  18
  19 For this we'll use the included sample web page in the sdk.
  20
  21 ### Step 1
  22
  23 Create a new directory for your application:
  24
  25 ```
  26 mkdir my-app
  27 cd my-app
  28 ```
  29
  30 ### Step 2
  31
  32 Copy the sample code from the SDK. We'll assume that the $WASM_SDK variable points to it.
  33
  34 ```
  35 cp $WASM_SDK/sample.html .
  36 cp $WASM_SDK/sample.cs .
  37 ```
  38
  39 ### Step 3
  40
  41 Compile and package your application.
  42
  43 ```
  44 csc /target:library sample.cs
  45 mono $WASM_SDK/packager.exe sample.dll
  46 ```
  47
  48 The package command will generate a `runtime.js` file that will properly load the runtime and call `App.Init` after that.
  49 It will copy the required files such as the runtime and class libraries.
  50
  51 ### Step 4
  52
  53 Launch the provided webserver:
  54
  55 ```
  56 python $WASM_SDK/server.py
  57 ```
  58
  59 Go to `http://localhost:8000/sample.html`
  60
  61
  62 # Debugging
  63
  64 The debugger requires dotnet core version 2.1.301 or greater installed.
  65
  66 To experiment with the debugger, do the following steps:
  67
  68 - When calling `packager.exe` pass the `-debug` argument to it.
  69 - Start Chrome with remote debugging enabled (IE `/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome\ Canary --remote-debugging-port=9222`)
  70 - Run the proxy: `dotnet dbg-proxy/ProxyDriver.dll`
  71 - Connect to the remote debugged Chrome and pick the page which is running the wasm code
  72 - Rewrite the request URL (just the `ws` argument) to use the proxy port instead of the browser port
  73 - Refresh the debugged page and you should be set
  74
  75 Beware that the debugger is in active development so bugs and missing features will be present.
  76
  77 # AOT development
  78
  79 AOT experimentation happens with the following steps:
  80
  81 1) from `sdks` and configure it to disable all but WASM and BCL. (See sdks/Make.config.sample)
  82 2) from `sdks/builds` hit `make package`
  83 3) from `sdks/wasm` hit `make build`
  84 4) from `sdks/wasm` hit `make build-aot-sample`
  85 4) from `sdks/wasm/aot` hit `~/.jsvu/sm aot-driver.js`
  86
  87 If you don't have jsvu installed, run `make toolchain` from `sdks/wasm`. It requires a recent version of node installed in your system.
  88
  89 Now you can experiment with the `aot-sample` and `link-sample` make targets to try the toolchain. The first invokes the AOT compiler and the second links the results.
  90
  91 To update the runtimes used use the following make target in `sdks/build`
  92
  93 `package-wasm-interp` for the interpreter-based runtime
  94 `package-wasm-aot` for the aot compiler
  95 `package-wasm-aot-runtime` for the wasm runtime that works with AOT'd code.
  96
  97
  98 To update the aot compiler:
  99 ```
 100 make -C sdks/builds package-wasm-aot-compiler
 101 make -C sdks/wasm aot-sample
 102 make -C sdks/wasm link-sample
 103 ```
 104
 105 To update the aot runtime:
 106 ```
 107 make -C sdks/builds package-wasm-aot
 108 make -C sdks/wasm aot-sample
 109 make -C sdks/wasm link-sample
 110 ```
 111
 112 # Notes
 113
 114 [1]: https://github.com/kripken/emscripten
 115
 116 [2]: https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs