sdks/wasm/README.md

   1 # Contents
   2
   3 > **_Note:_** Recent changes have occurred to the directory structure for `Available WebAssembly Runtime Builds` (see below diagrams).  All builds can now be found in one directory `sdk/wasm/builds`.  This was necessary to start supporting more options and functionality.
   4
   5 - Core libraries to be used with the runtime.  Generated by the bcl build step.
   6
   7     ```
   8         .
   9         |--- sdk/out/wasm-bcl
  10             |--- wasm               - Contains the DotNet Binary Core Library references and facades.
  11             |--- wasm_tools         - Contains the support tools used during build and distribution.
  12     ```
  13
  14 - Source support files for custom building the Webassembly Runtime
  15
  16     ```
  17         .
  18         |--- sdk/wasm/src
  19             |--- driver.c           - WebAssembly main driver program.
  20             |                           - Native interops with the library_mono.js
  21             |                           - Initializing and starting mono/
  22             |                           - Loading of assemblies
  23             |                           - etc ...
  24             |
  25             |--- library_mono.js    - Javascript low level backing support for Mono.
  26             |                           - Message pumping
  27             |                           - Loading and runnning the mono runtime.
  28             |                           - Setting environment variables
  29             |                           - AOT Profiler support
  30             |                           - Debugger support routines
  31             |
  32             |--- corebindings.c     - Native interface providing support for:
  33             |                           - Bindings for Core Javascript Objects
  34             |                           - Routines for calling managed code using FQN
  35             |                           - Marshalling code for js <-> managed objects
  36             |                           - etc ...
  37             |
  38             |--- binding_support.js - Javascript low level backing support for `corebindings.c`.
  39             |
  40             |--- dotnet_support.js  - Javascript low level backing support routines used by Blazor.
  41             |
  42             |--- zlib-helper.c      - Native interface providing support for zlib compression for System.IO.Compression.
  43             |
  44             |--- pinvoke-tables-default.h - Native pinvoke interface - this is a generated file.
  45
  46     ```
  47
  48 - Available WebAssembly Runtime Builds
  49
  50     ```
  51         .
  52         |--- sdk/wasm/builds
  53             |--- debug                  - Debug build of the runtime.
  54                 |--- corebindings.o         - Runtime linked lib - NOT DISTRIBUTED
  55                 |--- driver.o               - Runtime linked lib - NOT DISTRIBUTED
  56                 |--- mono.js                - Mono WebAssembly implementations
  57                 |--- mono.wasm              - Mono WebAssembly implementations
  58                 |--- mono.wasm.map          - Mono WebAssembly implementations
  59                 |--- zlib-helper.o          - Runtime linked lib - NOT DISTRIBUTED
  60             |--- release                - Release build of the runtime.
  61                 |--- corebindings.o         - Runtime linked lib - NOT DISTRIBUTED
  62                 |--- driver.o               - Runtime linked lib - NOT DISTRIBUTED
  63                 |--- mono.js                - Mono WebAssembly implementations
  64                 |--- mono.wasm              - Mono WebAssembly implementations
  65                 |--- zlib-helper.o          - Runtime linked lib - NOT DISTRIBUTED
  66             |--- threads-debug          - Debug build that includes pthreads.
  67                 |--- corebindings.o         - Runtime linked lib - NOT DISTRIBUTED
  68                 |--- driver.o               - Runtime linked lib - NOT DISTRIBUTED
  69                 |--- mono.js                - Mono WebAssembly implementations
  70                 |--- mono.wasm              - Mono WebAssembly implementations
  71                 |--- mono.wasm.map          - Mono WebAssembly implementations
  72                 |--- mono.js.mem            - Mono WebAssembly implementations
  73                 |--- mono.worker.js         - pthreads worker.  File must be deployed with the rest of the generated code files.
  74                 |--- zlib-helper.o          - Runtime linked lib - NOT DISTRIBUTED
  75             |--- threads-release        - Release build that includes pthreads.
  76                 |--- corebindings.o         - Runtime linked lib - NOT DISTRIBUTED
  77                 |--- driver.o               - Runtime linked lib - NOT DISTRIBUTED
  78                 |--- mono.js                - Mono WebAssembly implementations
  79                 |--- mono.wasm              - Mono WebAssembly implementations
  80                 |--- mono.wasm.map          - Mono WebAssembly implementations
  81                 |--- mono.js.mem            - Mono WebAssembly implementations
  82                 |--- mono.worker.js         - pthreads worker.  File must be deployed with the rest of the generated code files.
  83                 |--- zlib-helper.o          - Runtime linked lib - NOT DISTRIBUTED
  84
  85     ```
  86
  87     _Note:_ In the above directories the only files that need to be distributed are the ones prefixed with **mono.***.
  88
  89     _Note:_ The **`mono.worker.js`** and **`mono.js.mem`** files must be deployed with the rest of the generated code files if using the runtimes for threads.
  90
  91 # Requirements
  92
  93 Mono requires the latest [emscripten][1] installed and built. Emscripten is *not* required if simply using the sample.
  94
  95 # Compiling mono
  96
  97 ## Commands for compiling mono
  98
  99 ``` bash
 100
 101 make -C sdks/builds provision-wasm
 102 make -C sdks/builds archive-wasm  NINJA=
 103 make -C sdks/builds package-wasm-runtime package-wasm-runtime-threads package-wasm-cross package-wasm-bcl
 104
 105 ```
 106
 107
 108 # Sample
 109
 110 See [Getting Started Guides](./docs/getting-started)
 111
 112
 113 # Testing instructions
 114
 115 ## WebAssembly
 116
 117 First, ensure the `runtime`, `AOT` and `bcl` have been built and packaged in the `sdks/out` directory:
 118
 119 ```bash
 120 make -C sdks/builds package-wasm-runtime package-wasm-runtime-threads package-wasm-cross package-wasm-bcl
 121 ```
 122
 123 Build the test runner and test suites
 124
 125 ```bash
 126 make -C sdks/wasm build
 127 ```
 128
 129
 130 Right now the following targets are available:
 131
 132 - mono: Executes the previous `package-wasm-*` step above.
 133 - build: Build the test runner and test suites
 134 - run-all-mini: Run mini test suite
 135 - run-all-corlib: Run corlib test suite
 136 - run-all-system: Run System test suite
 137 - run-all-system-core: Run System.Core test suite
 138 - run-all-binding: Run bindings test suite
 139 - run-browser-tests: Run tests that require a browser environment
 140 - build-aot-all: Build all AOT samples and tests
 141 - run-aot-all: Run all AOT samples and tests
 142 - build-aot-sample: Build hello world AOT sample
 143 - run-aot-sample: Run hello world AOT sample
 144 - build-interp-sample: Build hello world AOT interpreter sample
 145 - run-interp-sample: Run hello world AOT interpreter sample
 146 - build-aot-bindings-sample: Build sample using bindings
 147 - build-aot-bindings-interp-sample: Build sample using bindings
 148 - clean: cleans the wasm directory
 149
 150 For bcl or runtime changes, you must manually run the corresponding build/package steps in `builds`.
 151 For test suite changes, it's enough to just rerun the local target.
 152
 153
 154 # Debugging
 155
 156 The debugger requires dotnet core version 2.1.301 or greater installed.
 157
 158 To experiment with the debugger, do the following steps:
 159
 160 - When calling `packager.exe` pass the `-debug` argument to it.
 161 - Start Chrome with remote debugging enabled (IE `/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222`)
 162 - Run the proxy: `dotnet run -p ProxyDriver/ProxyDriver.csproj`
 163 - Connect to the proxy by visiting http://localhost:9300/ and select the tab you wish to debug from the list of tabs
 164 - Refresh the debugged page and you should be set
 165
 166 Beware that the debugger is in active development so bugs and missing features will be present.
 167
 168 # WebAssembly packager.exe
 169
 170 Read usage information about the utility see [WebAssembly packager.exe](./docs/packager.md)
 171
 172 # Threading support
 173
 174 To build the runtime with pthread support use the following make target:
 175
 176 ``` bash
 177 make -C sdks/wasm runtime-threads
 178 ```
 179
 180 -- or --
 181
 182 ```bash
 183 make -C sdks/builds package-wasm-runtime-threads
 184 ```
 185
 186 During the main build two directories will be created:
 187
 188 ```
 189     .
 190     |--- sdk/wasm/builds
 191         |--- threads-debug          - Debug build that includes pthreads.
 192             |--- corebindings.o         - Runtime linked lib - NOT DISTRIBUTED
 193             |--- driver.o               - Runtime linked lib - NOT DISTRIBUTED
 194             |--- mono.js                - Mono WebAssembly implementations
 195             |--- mono.wasm              - Mono WebAssembly implementations
 196             |--- mono.wasm.map          - Mono WebAssembly implementations
 197             |--- mono.js.mem            - Mono WebAssembly implementations
 198             |--- mono.worker.js         - pthreads worker.  File must be deployed with the rest of the generated code files.
 199             |--- zlib-helper.o          - Runtime linked lib - NOT DISTRIBUTED
 200         |--- threads-release        - Release build that includes pthreads.
 201             |--- corebindings.o         - Runtime linked lib - NOT DISTRIBUTED
 202             |--- driver.o               - Runtime linked lib - NOT DISTRIBUTED
 203             |--- mono.js                - Mono WebAssembly implementations
 204             |--- mono.wasm              - Mono WebAssembly implementations
 205             |--- mono.wasm.map          - Mono WebAssembly implementations
 206             |--- mono.js.mem            - Mono WebAssembly implementations
 207             |--- mono.worker.js         - pthreads worker.  File must be deployed with the rest of the generated code files.
 208             |--- zlib-helper.o          - Runtime linked lib - NOT DISTRIBUTED
 209
 210 ```
 211
 212 _Note:_ The **`mono.worker.js`** and **`mono.js.mem`** files  must be deployed with the rest of the generated code files if using these two runtimes.
 213
 214
 215 # AOT support
 216
 217 AOT support is enabled by passing --aot to the packager.
 218
 219 This depends on building the cross compiler which can be done using:
 220
 221 ``` bash
 222 make -C sdks/wasm cross
 223 ```
 224
 225 If you don't have jsvu installed, run `make toolchain` from `sdks/wasm`. It requires a recent version of node installed in your system.
 226
 227 Run `make run-aot-sample` to run an aot-ed hello world sample.
 228
 229 To build and run AOT test suites:
 230
 231 ``` bash
 232 make -C sdks/wasm build-aot-<suite name>
 233 make -C sdks/wasm check-aot-<suite name>
 234 ```
 235
 236 ## AOT Bindings sample
 237
 238 To build the `sample` that uses bindings and http.
 239
 240 ``` bash
 241 make -C sdks/wasm build-aot-bindings-sample
 242 ```
 243
 244 This will build the `sample` in the `wasm/bin/aot-bindings-sample` ready to be served for browser consumption.
 245
 246 # Notes
 247
 248 [1]: https://github.com/kripken/emscripten
 249
 250 [2]: https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs