sdks/wasm/README.md

   1 # Contents
   2 - **sdk/out/wasm-bcl/wasm** directory: Core libraries to be used with the runtime.
   3 - **driver.c**, **libmonosgen-2.0.a**, **library_mono.js**, **binding_support.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 # Requirements
   9
  10 Mono requires the latest [emscripten][1] installed and built. Emscripten is *not* required if simply using the sample.
  11
  12 The pre-built binaries are compiled using the following command line for the debug build:
  13
  14 ``` bash
  15 emcc -s WASM=1 -s ALLOW_MEMORY_GROWTH=1 -s BINARYEN=1 -s "BINARYEN_TRAP_MODE='clamp'" -s ALIASING_FUNCTION_POINTERS=0 -s NO_EXIT_RUNTIME=1 -s "EXTRA_EXPORTED_RUNTIME_METHODS=['ccall', 'FS_createPath', 'FS_createDataFile', 'cwrap', 'setValue', 'getValue', 'UTF8ToString']" -s EMULATED_FUNCTION_POINTERS=1 -g4 -Os -s ASSERTIONS=1 --js-library library_mono.js --js-library binding_support.js --js-library dotnet_support.js driver.o mono/sdks/out/wasm-runtime-release/lib/{libmono-ee-interp.a,libmono-native.a,libmonosgen-2.0.a,libmono-ilgen.a,libmono-icall-table.a} -o debug/mono.js
  16
  17 ```
  18
  19 # Compiling mono
  20
  21
  22 ## Commands for compiling mono
  23
  24 ``` bash
  25
  26 make -C sdks/builds provision-wasm
  27 make -C sdks/builds archive-wasm  NINJA=
  28 make -C sdks/builds package-wasm-runtime package-wasm-cross package-wasm-bcl
  29
  30 ```
  31
  32 # Sample
  33
  34 See [Getting Started Guides](./docs/getting-started)
  35
  36
  37 # Testing instructions
  38
  39 ## WebAssembly
  40
  41 First, ensure the `runtime`, `AOT` and `bcl` have been built and packaged in the `sdks/out` directory:
  42
  43 ```bash
  44 make -C sdks/builds package-wasm-runtime package-wasm-cross package-wasm-bcl
  45 ```
  46
  47 Build the test runner and test suites
  48
  49 ```bash
  50 make -C sdks/wasm build
  51 ```
  52
  53
  54 Right now the following targets are available:
  55
  56 - mono: Executes the previous `package-wasm-*` step above.
  57 - build: Build the test runner and test suites
  58 - run-all-mini: Run mini test suite
  59 - run-all-corlib: Run corlib test suite
  60 - run-all-system: Run System test suite
  61 - run-all-system-core: Run System.Core test suite
  62 - run-all-binding: Run bindings test suite
  63 - run-browser-tests: Run tests that require a browser environment
  64 - build-aot-all: Build all AOT samples and tests
  65 - run-aot-all: Run all AOT samples and tests
  66 - build-aot-sample: Build hello world AOT sample
  67 - run-aot-sample: Run hello world AOT sample
  68 - build-interp-sample: Build hello world AOT interpreter sample
  69 - run-interp-sample: Run hello world AOT interpreter sample
  70 - build-aot-bindings-sample: Build sample using bindings
  71 - build-aot-bindings-interp-sample: Build sample using bindings
  72 - clean: cleans the wasm directory
  73
  74 For bcl or runtime changes, you must manually run the corresponding build/package steps in `builds`.
  75 For test suite changes, it's enough to just rerun the local target.
  76
  77
  78 # Debugging
  79
  80 The debugger requires dotnet core version 2.1.301 or greater installed.
  81
  82 To experiment with the debugger, do the following steps:
  83
  84 - When calling `packager.exe` pass the `-debug` argument to it.
  85 - Start Chrome with remote debugging enabled (IE `/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome\ Canary --remote-debugging-port=9222`)
  86 - Run the proxy: `dotnet run -p ProxyDriver/ProxyDriver.csproj`
  87 - Connect to the remote debugged Chrome and pick the page which is running the wasm code
  88 - Rewrite the request URL (just the `ws` argument) to use the proxy port (9300 by default for ProxyDriver) instead of the browser port
  89 - Refresh the debugged page and you should be set
  90
  91 Beware that the debugger is in active development so bugs and missing features will be present.
  92
  93 # WebAssembly packager.exe
  94
  95 Read usage information about the utility see [WebAssembly packager.exe](./docs/packager)
  96
  97 # AOT support
  98
  99 AOT support is enabled by passing --aot to the packager.
 100
 101 This depends on building the cross compiler which can be done using:
 102
 103 ``` bash
 104 make -C sdks/wasm cross
 105 ```
 106
 107 If you don't have jsvu installed, run `make toolchain` from `sdks/wasm`. It requires a recent version of node installed in your system.
 108
 109 Run `make run-aot-sample` to run an aot-ed hello world sample.
 110
 111 To build and run AOT test suites:
 112
 113 ``` bash
 114 make -C sdks/wasm build-aot-<suite name>
 115 make -C sdks/wasm check-aot-<suite name>
 116 ```
 117
 118 ## AOT Bindings sample
 119
 120 To build the `sample` that uses bindings and http.
 121
 122 ``` bash
 123 make -C sdks/wasm build-aot-bindings-sample
 124 ```
 125
 126 This will build the `sample` in the `wasm/bin/aot-bindings-sample` ready to be served for browser consumption.
 127
 128 # Notes
 129
 130 [1]: https://github.com/kripken/emscripten
 131
 132 [2]: https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs