|
| 1 | +# ExecuTorch Wasm Build |
| 2 | + |
| 3 | +This guide describes how to build ExecuTorch for WebAssembly (Wasm). |
| 4 | + |
| 5 | +## Quick Start |
| 6 | + |
| 7 | +To quickly test the build, you can run the following commands |
| 8 | + |
| 9 | +```bash |
| 10 | +cd executorch # To the top level dir |
| 11 | + |
| 12 | +source .ci/scripts/setup-emscripten.sh # Install Emscripten and set up the environment variables |
| 13 | + |
| 14 | +bash examples/wasm/test_build_wasm.sh # Run the test build script |
| 15 | +``` |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +- [Emscripten](https://emscripten.org/docs/getting_started/Tutorial.html) |
| 20 | + |
| 21 | +## Generate Models |
| 22 | + |
| 23 | +JavaScript does not have direct access to the host file system. To load a model, it needs to be preloaded or embedded into the virtual file system. In this example, models in the `./models/` directory are embedded by default. We will then build `executorch_runner` in Wasm. |
| 24 | + |
| 25 | +1. Following the setup guide in [Setting up ExecuTorch](https://pytorch.org/executorch/main/getting-started-setup) |
| 26 | +you should be able to get the basic development environment for ExecuTorch working. |
| 27 | + |
| 28 | +2. Using the script `portable/scripts/export.py` generate a model binary file by selecting a |
| 29 | +model name from the list of available models in the `examples/models` dir. |
| 30 | + |
| 31 | +```bash |
| 32 | +cd executorch # To the top level dir |
| 33 | + |
| 34 | +mkdir models |
| 35 | + |
| 36 | +# To get a list of example models |
| 37 | +python3 -m examples.portable.script.export -h |
| 38 | + |
| 39 | +# To generate a specific pte model into the models/ directory |
| 40 | +python3 -m examples.portable.scripts.export --model_name="mv2" --output_dir="models/" # for MobileNetv2 |
| 41 | + |
| 42 | +# This should generate ./models/mv2.pte file, if successful. |
| 43 | +``` |
| 44 | + |
| 45 | +Use -h (or --help) to see all the supported models. For the browser example, make sure you have a model with the file name `model.pte` in the `./models/` directory. |
| 46 | + |
| 47 | +3. Once we have the model binaries (.pte) in `./models/`, we can build `executor_runner` in Wasm with Emscripten. When calling `emcmake cmake`, you can pass the `-DWASM_MODEL_DIR=<path>` option to specify the directory containing the model files instead of `./models/`. |
| 48 | + |
| 49 | +```bash |
| 50 | +./install_executorch.sh --clean |
| 51 | +(mkdir cmake-out-wasm \ |
| 52 | + && cd cmake-out-wasm \ |
| 53 | + && emcmake cmake -DEXECUTORCH_PAL_DEFAULT=posix ..) \ |
| 54 | + && cmake --build cmake-out-wasm -j32 --target executor_runner |
| 55 | +``` |
| 56 | + |
| 57 | +If you need to rebuild `executor_runner` after modifying the contents of `./models/`, you can run the following command |
| 58 | + |
| 59 | +```bash |
| 60 | +cmake --build cmake-out-wasm -j32 --target executor_runner --clean-first |
| 61 | +``` |
| 62 | + |
| 63 | +4. Run the model with Node.js. Emscripten should come preinstalled with a compatible version of Node.js. If you have an incompatible version of Node.js installed, you can use the Emscripten-provided version by running `$EMSDK_NODE` instead of `node`. |
| 64 | + |
| 65 | +```bash |
| 66 | +# Run the tool on the generated model. |
| 67 | +node cmake-out-wasm/executor_runner.js --model_path mv2.pte |
| 68 | +``` |
| 69 | + |
| 70 | +5. You can also run the model in the browser. Note that you cannot pass command line arguments to the browser version of the tool. By default, the program will load the model `model.pte` and run it. Several browsers do not support `file://` XHR requests to load the Wasm file. To get around this, you can use a local web server. For example, with Python: |
| 71 | + |
| 72 | +```bash |
| 73 | +python3 -m http.server --directory cmake-out-wasm |
| 74 | +``` |
| 75 | + |
| 76 | +The page will be available at http://localhost:8000/executor_runner.html. |
| 77 | + |
| 78 | +## Common Issues |
| 79 | + |
| 80 | +### CompileError: WebAssembly.instantiate() [...] failed: expected table index 0... |
| 81 | + |
| 82 | +This seems to be an issue with Node.js v16. Emscripten should come preinstalled with a compatible version of Node.js. You can use the Emscripten-provided version by running `$EMSDK_NODE` instead of `node`. |
| 83 | + |
| 84 | +```bash |
| 85 | +echo $EMSDK_NODE |
| 86 | +.../emsdk/node/22.16.0_64bit/bin/node # example output |
| 87 | +``` |
| 88 | + |
| 89 | +### Failed to open [...]: No such file or directory (44) |
| 90 | + |
| 91 | +The file may not have been present while building the Wasm binary. You can rebuild with the following command |
| 92 | + |
| 93 | +```bash |
| 94 | +cmake --build cmake-out-wasm -j32 --target executor_runner --clean-first |
| 95 | +``` |
| 96 | + |
| 97 | +The path may also be incorrect. The files in the `WASM_MODEL_DIR` are placed into the root directory of the virtual file system, so you would use `--model_path mv2.pte` instead of `--model_path models/mv2.pte`, for example. |
0 commit comments