Skip to content

Commit cd6d0dc

Browse files
ConarnarConarnar
committed
Added readme for Wasm extension
1 parent 9d86cbe commit cd6d0dc

File tree

1 file changed

+150
-0
lines changed

1 file changed

+150
-0
lines changed

‎extension/wasm/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
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+
You may also use the selective build options found in the [Kernel Library Selective Build guide](../../docs/source/kernel_library_selective_build.md) or with optimized kernels using 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+
Alternatively, you may want to have your code come after the JS library code.
67+
68+
```html
69+
<script src="executorch_wasm_lib.js"></script>
70+
<script>
71+
const et = Module; // Assign Module into et for ease of use
72+
et.onRuntimeInitialized = () => {
73+
// Emscripten calls Module.onRuntimeInitialized once the runtime is ready.
74+
const model = et.Module.load("mv2.pte");
75+
// ...
76+
}
77+
</script>
78+
```
79+
80+
### Building for Node.js
81+
82+
You can follow the [Building for Web](#building-for-web) instructions and access the API with:
83+
84+
```js
85+
const et = require("./executorch_wasm_lib");
86+
```
87+
88+
However, 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` or `--post-js` to prepend or append your file to the end of the JS output.
89+
90+
```cmake
91+
add_executable(my_project) # Emscripten outputs this as a JS and Wasm file
92+
target_link_libraries(my_project PRIVATE executorch_wasm)
93+
target_link_options(my_project PRIVATE --post-js my_code.js) # Add any additional link options here
94+
```
95+
96+
The output `my_project.js` should contain both the emitted JS code and the contents of `my_code.js`.
97+
98+
## JavaScript API
99+
100+
### Module
101+
- `static load(data)`: Load a model from a file or a buffer.
102+
- `getMethods()`: Returns the list of methods in the model.
103+
- `loadMethod(methodName)`: Load a method from the model.
104+
- `getMethodMetadata(methodName)`: Get the metadata of a method.
105+
- `execute(methodName, inputs)`: Execute a method with the given inputs.
106+
- `forward(inputs)`: Execute the forward method with the given inputs.
107+
- `delete()`: Delete the model from memory.
108+
109+
### Tensor
110+
- `static zeroes(shape, dtype=ScalarType.Float)`: Create a tensor of zeros with the given shape and dtype.
111+
- `static ones(shape, dtype=ScalarType.Float)`: Create a tensor of ones with the given shape and dtype.
112+
- `static full(shape, value, dtype=ScalarType.Float)`: Create a tensor of the given value with the given shape and dtype
113+
- `static fromArray(shape, array, dtype=ScalarType.Float, dimOrder=[], strides=[])`: Create a tensor from a JavaScript array.
114+
- `static fromIter(shape, iter, dtype=ScalarType.Float, dimOrder=[], strides=[])`: Create a tensor from an iterable.
115+
- `delete()`: Delete the tensor from memory.
116+
- `scalarType`: The scalar type of the tensor.
117+
- `data`: The data buffer of the tensor.
118+
- `sizes`: The sizes of the tensor.
119+
120+
### MethodMeta
121+
- `name`: The name of the method.
122+
- `inputTags`: The input tags of the method.
123+
- `inputTensorMeta`: The input tensor metadata of the method.
124+
- `outputTags`: The output tags of the method.
125+
- `outputTensorMeta`: The output tensor metadata of the method.
126+
- `attributeTensorMeta`: The attribute tensor metadata of the method.
127+
- `memoryPlannedBufferSizes`: The memory planned buffer sizes of the method.
128+
- `backends`: The backends of the method.
129+
- `numInstructions`: The number of instructions in the method.
130+
- These are value types and do not need to be manually deleted.
131+
132+
### TensorInfo
133+
- `sizes`: The sizes of the tensor.
134+
- `dimOrder`: The dimension order of the tensor.
135+
- `scalarType`: The scalar type of the tensor.
136+
- `isMemoryPlanned`: Whether the tensor is memory planned.
137+
- `nBytes`: The number of bytes in the tensor.
138+
- `name`: The name of the tensor.
139+
- These are value types and do not need to be manually deleted.
140+
141+
### ScalarType
142+
- Only `Float` and `Long` are currently supported.
143+
- `value`: The int constant value of the enum.
144+
- `name`: The `ScalarType` as a string.
145+
146+
### Tag
147+
- `value`: The int constant value of the enum.
148+
- `name`: The `Tag` as a string.
149+
150+
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)