Compile your custom chips to WASM for use with VS Code or the Wokwi CLI.
Custom components written with the Chips API can be compiled into WebAssembly (WASM) for use with the Wokwi VS Code extension or the Wokwi CLI.The WASM binary can be compiled by the Wokwi CLI, GitHub Actions, a container, or locally. This guide will cover all four approaches.
The simplest way to get started is by cloning/forking the inverter-chip example repository from the Wokwi GitHub. You can then compile locally, use the dev container feature from VS Code, or push to GitHub to compile the WASM binary.
A custom chip requires a [[chip]] key in wokwi.toml. This key specifies the name and binary used by the custom chip. Wokwi also requires a JSON file that describes the pinout of the chip. This JSON file should have the same name as the WASM binary, but with its extension changed to .json instead of .wasm, e.g. inverter.chip.wasm is paired with inverter.chip.json.
Custom Chip Definitions
Learn how to configure the chip JSON file properly
An example excerpt from wokwi.toml:
[[chip]]name = 'inverter' # To use the chip in diagram.json, add a part with "chip-inverter" type.binary = 'chips/inverter.chip.wasm'
Multiple chips can be added to the same project by adding multiple [[chip]] keys, each with different name and binary values.
If you are cloning/forking the inverter chip repository, you can skip this section.
If you are setting up your project from scratch, you will need to ensure that the Wokwi C API is present within your source files. The easiest way to ensure this is to use the Wokwi CLI to compile your chip, as it will fetch the required files. It is also available from wokwi.com/api/chips/wokwi-api.h.
You need to ensure that the Wokwi API is included in your project, otherwise you will not be able to make use of the Chips API.
Replace main.c with your source file name. The wokwi-cli will automatically fetch the required toolchain + SDK, and will output a WASM binary which is ready to use with Wokwi.
Generate a Makefile for more advanced projects: wokwi-cli chip makefile -n my_chip [source_files ...]
Additional examples are available via the -h/--help flag in wokwi-cli.
If you have cloned the inverter chip repository, then it has been configured and is ready for you to modify it to your needs. It will automatically compile the binary once a push is made to the repository, and will also automatically generate a GitHub release if you push a tag that starts with a “v”, e.g. v1.0.3.
If you did not clone the inverter chip repository and are wanting to configure your own actions, then consider looking at the build workflow file.
The inverter chip repository comes with a dev container configuration file that will automatically handle setting up a Docker container for you to build your binaries in.
1
Open in container
Press F1 and search for “Dev Containers: Open Folder in Container…”.Alternatively, click the icon bottom left of the VS Code window, and click on “Reopen in Container”.
2
Build
Once the container is ready, you should be presented with a terminal window where you can now run make. This will run the Makefile in the repository, and your generated WASM files should appear in dist/.
You can use the prebuilt wokwi/builder-clang-wasm image to compile your project in a Docker environment.Navigate to the root of your project and run:
docker run --rm -u 1000:1000 -v ${PWD}:/src wokwi/builder-clang-wasm:latest make
After fetching the image, this command will automatically execute the Makefile in the project. In the case of the inverter example, it will create the dist/ directory, compile the binary into dist/chip.wasm and copy chip.json to dist/.
You can enter an interactive session with the following:
docker run --rm -it -u 1000:1000 -v ${PWD}:/src wokwi/builder-clang-wasm:latest
The argument -u 1000:1000 is required since otherwise you may run into issues with permissions (such as the container being unable to open files or create directories). If your computer has multiple users, you may have to update the value to something other than 1000 - check the output of the id command on the host to get the proper value.
You will need to configure your environment to be able to build WASM assemblies locally. This part of the documentation is written with Ubuntu/Debian distros in mind, so you may have to adjust these instructions to your machine.
Extract libclang_rt-27.0/wasm32-unknown-wasi/libclang_rt.builtins.a to /usr/lib/llvm-???/lib/clang/???/lib/wasi/
Replace the ??? in the path above with the currently installed LLVM version number on your system. Check by running clang -v and looking at the major release number.
Rename the copied file from libclang_rt.builtins.a to libclang_rt.builtins-wasm32.a
You may have to update the Makefile to remove the --sysroot argument, as wasi-libc will be installed to a different directory than what --sysroot is set to.If successful, you should now have chip.wasm under dist/!
