{"id":20009827,"url":"https://github.com/plsyssec/wasix","last_synced_at":"2026-05-09T20:09:19.533Z","repository":{"id":144629542,"uuid":"368010144","full_name":"PLSysSec/wasix","owner":"PLSysSec","description":null,"archived":false,"fork":false,"pushed_at":"2022-08-24T21:29:27.000Z","size":3916,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-12T14:37:46.581Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PLSysSec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-17T00:03:30.000Z","updated_at":"2023-03-20T18:46:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb8cb736-841f-4c68-9e98-47e31e6f2f81","html_url":"https://github.com/PLSysSec/wasix","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fwasix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fwasix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fwasix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PLSysSec%2Fwasix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PLSysSec","download_url":"https://codeload.github.com/PLSysSec/wasix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241447522,"owners_count":19964314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T07:17:11.277Z","updated_at":"2026-05-09T20:09:19.475Z","avatar_url":"https://github.com/PLSysSec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Usage\n\n## Use make\nUsing `make` is the simplest way to interact with wasix.\n\n`make gen [NUM=X] [SIZE=Y]`: generates X tests, where each test has Y syscalls, in `test/`\n\n`make run [OS=OS_NAME]`: run all test in test/ and generate traces in `traces/`. Trace files have `OS_NAME` as part of their names.\n\n`make check`: checks trace files in traces/ and generates a HTML report there.\n\n`make all [NUM=X] [SIZE=Y] [OS=OS_NAME]`: equivalent to run all commands above\n\nIf not specified, defaults are `X=10, Y=30, OS=not_specified`\n\n`run.sh` and `test.sh` each contains an example make commands.\n\n## Use wasix\nYou can also use the `wasix` script directly to specify where you want to put tests and traces.\n```\nusage: wasix [-h] (--gen | --run | --check | --all) [--num NUM] [--size SIZE] [--test_dir TEST_DIR] [--trace_dir TRACE_DIR] [--os OS]\n\nA differential testing tool for WASI-compatible WASM runtimes\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --gen                 generate tests\n  --run                 run tests and generate trace files\n  --check               compare trace files\n  --all                 gen, run, and check; needs all other flags defined\n  --num NUM             number of tests\n  --size SIZE           size of each test\n  --test_dir TEST_DIR   where wasm tests are/should be located\n  --trace_dir TRACE_DIR\n                        where traces file are/should be located\n  --os OS               the name of current os\n```\n\n## Check bugs\nWe manually wrote several tests that reproduce the bugs found by wasix.\nThese tests are located under `bug/`\nTo run them and see the result, use\n\n`make bug-comp`: compiles all the tests under bug/\n\n`make bug-run`: run all test and generate trace in bug-trace/\n\n`make bug-check`: check traces in bug-trace/ and generate a HTML report\n\n`make bug-all`: equivalent to run all commands above\n\n# About Wasix\nAs a cross testing tool for WASM runtimes, focusing on WASI implementations, Wasix can automatically\n\n- generate random WASI-rich tests\n- compile and run tests with different WASM runtimes\n- check trace files generated by tests\n- generate a report showing differences among runtimes in HTML\n\nWe have manually written several C files that can reproduce bugs we found using Wasix. To run them, see the [Check bugs](#check-bugs)\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails open=\"open\"\u003e\n  \u003csummary\u003e\u003ch2 style=\"display: inline-block\"\u003eTable of Contents\u003c/h2\u003e\u003c/summary\u003e\n  \u003cul\u003e\n    \u003cli\u003e\n      \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#use-make\"\u003eUse make\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#use-wasix\"\u003eUse wasix\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#check-bugs\"\u003eCheck bugs\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#dependencies\"\u003eInstalling Dependencies\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#install-wasi-sdk\"\u003eWASI SDK\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#wasmtime\"\u003eWasmtime\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#wasmer\"\u003eWasmer\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#lucet\"\u003eLucet\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#wavm\"\u003eWAVM\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#wamr\"\u003eWAMR\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#wasm3\"\u003eWasm3 (Not recommended)\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/details\u003e\n\n# Dependencies\n\n## Install WASI SDK\nWe use [WASI SDK](https://github.com/WebAssembly/wasi-sdk) to compile C tests to WASM.\nTo install WASI SDK, go to WASI SDK's [download page](https://github.com/WebAssembly/wasi-sdk/releases), choose the version for your OS.\nThen run:\n```\nwget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-[YOUR VERSION]}.tar.gz\ntar xvf wasi-sdk-12.0-[YOUR VERSION].tar.gz\n```\n\n**You need to export your WASI SDK path to `WASI_SDK_PATH`, which should be `current_dir/wasi-sdk-12.0`**\n\n\n## Install runtimes\nRun commands below to see if you already have the runtimes installed.\n```\nwasmtime --version\nwasmer --version\nlucet-wasi --version\nwasm3 --version\niwasm\nwavm version\n```\n\n### Wasmtime\nTo install [Wasmtime](https://github.com/bytecodealliance/wasmtime), run\n```\ncurl https://wasmtime.dev/install.sh -sSf | bash\n```\n\nTo use wasmtime, run\n```\nwasmtime *.wasm --dir \u003caccess file dir\u003e \n```\n\n### Wasmer\nTo install [wasmer](https://github.com/wasmerio/wasmer), run\n```\ncurl https://get.wasmer.io -sSfL | sh\n```\n\nTo use wasmer, run\n```\nwasmer *.wasm --dir \u003caccess file dir\u003e \n```\n\n### Lucet\nTo install [Lucet](https://github.com/bytecodealliance/lucet), see [instructions for Linux](https://bytecodealliance.github.io/lucet/Compiling-on-Linux.html) or [instructions for macOS](https://bytecodealliance.github.io/lucet/Compiling-on-macOS.html).\n\nWe installed Lucet on Ubuntu by doing:\n```\n# Install dependency\nsudo apt install curl ca-certificates cmake\n# Install Rust\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsource $HOME/.cargo/env\n# Install lucet\ngit clone https://github.com/bytecodealliance/lucet.git\ncd lucet\ngit submodule update --init --recursive\n# This is something ignored in the doc.\nsudo apt install libclang-dev\nexport LLVM_CONFIG_PATH=\"WASI_SDK_PATH/bin\"\nexport PATH=\"WASI_SDK_PATH/bin:$PATH\"\nmake install\n```\n\nTo use lucet, run \n```\nsource /opt/lucet/bin/setenv.sh\nlucetc-wasi -o *.so *.wasm\nlucet-wasi  *.so --dir  \u003cwasm path\u003e:\u003chost path\u003e\n#　e.g.  lucet-wasi  *.so --dir .:.\n```\n\n\n### WAVM\nTo install [WAVM](https://github.com/WAVM/WAVM), follow [the instruction](https://github.com/WAVM/WAVM/blob/master/Doc/GettingStarted.md) for your OS. \nFor Linux, run\n```\nwget https://github.com/WAVM/WAVM/releases/download/nightly%2F2021-05-10/wavm-0.0.0-prerelease-linux.deb\nsudo apt install ./wavm-0.0.0-prerelease-linux.deb\n```\n\nTo use WAVM, run\n```\nwavm run --mount-root \u003caccess file dir\u003e *.wasm\n```\n\n### WAMR\nWe only need the iwasm VM core from [WAMR](https://github.com/bytecodealliance/wasm-micro-runtime).\nTo install iwasm, follow [the instruction](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wamr.md), or run\n```\nsudo apt install build-essential cmake g++-multilib libgcc-8-dev lib32gcc-8-dev\nor\nbrew install cmake\n\ngit clone https://github.com/bytecodealliance/wasm-micro-runtime.git\ncd product-mini/platforms/\u003cFIND YOU OS\u003e/\nmkdir build\ncd build\ncmake .. -DWAMR_BUILD_AOT=1 -DWAMR_BUILD_LIBC_WASI=1\nmake\n```\nYou also need to export your build directory(where the `iwasm` binary locates) to `PATH`.\n\n### Wasm3\nTo install [Wasm3](https://github.com/wasm3/wasm3):\nfor MacOS\n```\nbrew install wasm3\n```\n\nfor linux, download the binary `wasm3-cosmopolitan.com` from [the release page](https://github.com/wasm3/wasm3/releases/tag/v0.4.9). It's supposed to run on Linux.\n\nRun ```wasm3 \u003cfile\u003e``` for executing.\n\nNote: seems at this time wasm3 doesn't support fstat.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplsyssec%2Fwasix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplsyssec%2Fwasix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplsyssec%2Fwasix/lists"}