Skip to content

Commit 134becb

Browse files
ConarnarConarnar
authored
Added readme for Wasm extension (#13131)
### Summary Added readme containing build instructions and API documentation for Wasm extension. ### Test plan N/A
1 parent caefefe commit 134becb

File tree

1 file changed

+130
-0
lines changed

1 file changed

+130
-0
lines changed

‎extension/wasm/README.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# ExecuTorch Wasm Extension
2+
3+
This directory contains the source code for the ExecuTorch Wasm extension. The extension is a C++ library that provides a JavaScript API for ExecuTorch models. The extension is compiled to WebAssembly and can be used in JavaScript applications.
4+
5+
## Installing Emscripten
6+
7+
[Emscripten](https://emscripten.org/index.html) is necessary to compile ExecuTorch for Wasm. You can install Emscripten with these commands:
8+
9+
```bash
10+
# Clone the emsdk repository
11+
git clone https://github.com/emscripten-core/emsdk.git
12+
cd emsdk
13+
14+
# Download and install version 4.0.10 of the SDK
15+
./emsdk install 4.0.10
16+
./emsdk activate 4.0.10
17+
18+
# Add the Emscripten environment variables to your shell
19+
source ./emsdk_env.sh
20+
```
21+
22+
## Building ExecuTorch for Wasm
23+
24+
To build ExecuTorch for Wasm, make sure to use the `emcmake cmake` command and to have `EXECUTORCH_BUILD_WASM` enabled. For example:
25+
26+
```bash
27+
# Configure the build with the Emscripten environment variables
28+
emcmake cmake . -DEXECUTORCH_BUILD_WASM=ON \
29+
-DCMAKE_BUILD_TYPE=Release \
30+
-Bcmake-out-wasm
31+
32+
# Build the Wasm extension
33+
cmake --build cmake-out-wasm --target executorch_wasm -j32
34+
```
35+
36+
To reduce the binary size, you may also use the selective build options found in the [Kernel Library Selective Build guide](../../docs/source/kernel-library-selective-build.md). You may also use optimized kernels with the `EXECUTORCH_BUILD_KERNELS_OPTIMIZED` option. Portable kernels are used by default.
37+
38+
### Building for Web
39+
40+
In your CMakeLists.txt, add the following lines:
41+
42+
```cmake
43+
add_executable(executorch_wasm_lib) # Emscripten outputs this as a JS and Wasm file
44+
target_link_libraries(executorch_wasm_lib PRIVATE executorch_wasm)
45+
target_link_options(executorch_wasm_lib PRIVATE ...) # Add any additional link options here
46+
```
47+
48+
You can find the Emscripten link options in the [emcc reference](https://emscripten.org/docs/tools_reference/emcc.html).
49+
50+
Building this should output `executorch_wasm_lib.js` and `executorch_wasm_lib.wasm` in the build directory. You can then use this file in your page.
51+
52+
```html
53+
<script>
54+
// Emscripten calls Module.onRuntimeInitialized once the runtime is ready.
55+
var Module = {
56+
onRuntimeInitialized: function() {
57+
const et = Module; // Assign Module into et for ease of use
58+
const model = et.Module.load("mv2.pte");
59+
// ...
60+
}
61+
}
62+
</script>
63+
<script src="executorch_wasm_lib.js"></script>
64+
```
65+
66+
### Building for Node.js
67+
68+
While the standard way to import a module in Node.js is to use the `require` function, doing so does not give you access to the [Emscripten API](https://emscripten.org/docs/api_reference/index.html) which would be stored in the globals. For example, you may want to use the [File System API](https://emscripten.org/docs/api_reference/Filesystem-API.html) in your unit tests, which cannot be done if the library is loaded with `require`. Instead, you can use the `--pre-js` option to prepend your file to the start of the JS output and behave similarly to the example in the [Web build](#building-for-web).
69+
70+
```cmake
71+
add_executable(my_project) # Emscripten outputs this as a JS and Wasm file
72+
target_link_libraries(my_project PRIVATE executorch_wasm)
73+
target_link_options(my_project PRIVATE --pre-js my_code.js) # Add any additional link options here
74+
```
75+
76+
The output `my_project.js` should contain both the emitted JS code and the contents of `my_code.js` prepended.
77+
78+
## JavaScript API
79+
80+
### Module
81+
- `static load(data)`: Load a model from a file or a buffer.
82+
- `getMethods()`: Returns the list of methods in the model.
83+
- `loadMethod(methodName)`: Load a method from the model.
84+
- `getMethodMetadata(methodName)`: Get the metadata of a method.
85+
- `execute(methodName, inputs)`: Execute a method with the given inputs.
86+
- `forward(inputs)`: Execute the forward method with the given inputs.
87+
- `delete()`: Delete the model from memory.
88+
89+
### Tensor
90+
- `static zeroes(shape, dtype=ScalarType.Float)`: Create a tensor of zeros with the given shape and dtype.
91+
- `static ones(shape, dtype=ScalarType.Float)`: Create a tensor of ones with the given shape and dtype.
92+
- `static full(shape, value, dtype=ScalarType.Float)`: Create a tensor of the given value with the given shape and dtype
93+
- `static fromArray(shape, array, dtype=ScalarType.Float, dimOrder=[], strides=[])`: Create a tensor from a JavaScript array.
94+
- `static fromIter(shape, iter, dtype=ScalarType.Float, dimOrder=[], strides=[])`: Create a tensor from an iterable.
95+
- `delete()`: Delete the tensor from memory.
96+
- `scalarType`: The scalar type of the tensor.
97+
- `data`: The data buffer of the tensor.
98+
- `sizes`: The sizes of the tensor.
99+
100+
### MethodMeta
101+
- `name`: The name of the method.
102+
- `inputTags`: The input tags of the method.
103+
- `inputTensorMeta`: The input tensor metadata of the method.
104+
- `outputTags`: The output tags of the method.
105+
- `outputTensorMeta`: The output tensor metadata of the method.
106+
- `attributeTensorMeta`: The attribute tensor metadata of the method.
107+
- `memoryPlannedBufferSizes`: The memory planned buffer sizes of the method.
108+
- `backends`: The backends of the method.
109+
- `numInstructions`: The number of instructions in the method.
110+
- These are value types and do not need to be manually deleted.
111+
112+
### TensorInfo
113+
- `sizes`: The sizes of the tensor.
114+
- `dimOrder`: The dimension order of the tensor.
115+
- `scalarType`: The scalar type of the tensor.
116+
- `isMemoryPlanned`: Whether the tensor is memory planned.
117+
- `nBytes`: The number of bytes in the tensor.
118+
- `name`: The name of the tensor.
119+
- These are value types and do not need to be manually deleted.
120+
121+
### ScalarType
122+
- Only `Float` and `Long` are currently supported.
123+
- `value`: The int constant value of the enum.
124+
- `name`: The `ScalarType` as a string.
125+
126+
### Tag
127+
- `value`: The int constant value of the enum.
128+
- `name`: The `Tag` as a string.
129+
130+
Emscripten's JavaScript API is also avaiable, which you can find more information about it in their [API Reference](https://emscripten.org/docs/api_reference/index.html).

0 commit comments

Comments
 (0)