{"id":24370083,"url":"https://github.com/unikraft/app-wamr","last_synced_at":"2025-07-29T02:08:05.007Z","repository":{"id":53468899,"uuid":"239382310","full_name":"unikraft/app-wamr","owner":"unikraft","description":"Web Assembly (WAMR) on Unikraft","archived":false,"fork":false,"pushed_at":"2023-10-23T09:07:14.000Z","size":18,"stargazers_count":9,"open_issues_count":0,"forks_count":8,"subscribers_count":9,"default_branch":"stable","last_synced_at":"2025-04-10T17:58:19.474Z","etag":null,"topics":["unikernel","unikraft-application","webassembly"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/unikraft.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}},"created_at":"2020-02-09T22:12:47.000Z","updated_at":"2024-04-04T09:47:35.000Z","dependencies_parsed_at":"2023-01-22T11:40:12.312Z","dependency_job_id":"b83995e2-7818-4250-9b62-14245a7a7890","html_url":"https://github.com/unikraft/app-wamr","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/unikraft/app-wamr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-wamr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-wamr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-wamr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-wamr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unikraft","download_url":"https://codeload.github.com/unikraft/app-wamr/tar.gz/refs/heads/stable","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unikraft%2Fapp-wamr/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267617643,"owners_count":24116208,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["unikernel","unikraft-application","webassembly"],"created_at":"2025-01-19T04:12:34.374Z","updated_at":"2025-07-29T02:08:04.962Z","avatar_url":"https://github.com/unikraft.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web Assembly (WAMR) on Unikraft\n\nThis application runs a wasm file.\nFollow the instructions below to set up, configure, build and run wamr.\n\nTo get started immediately, you can use Unikraft's companion command-line companion tool, [`kraft`](https://github.com/unikraft/kraftkit).\nStart by running the interactive installer:\n\n```console\ncurl --proto '=https' --tlsv1.2 -sSf https://get.kraftkit.sh | sudo sh\n```\n\nOnce installed, clone [this repository](https://github.com/unikraft/app-wamr) and run `kraft build`:\n\n```console\ngit clone https://github.com/unikraft/app-wamr wamr\ncd wamr/\nkraft build\n```\n\nThis will guide you through an interactive build process where you can select one of the available targets (architecture/platform combinations).\nOtherwise, we recommend building for `qemu/x86_64` like so:\n\n```console\nkraft build --target wamr-qemu-x86_64-initrd\n```\n\nOnce built, you can instantiate the unikernel via:\n\n```console\nkraft run --target wamr-qemu-x86_64-initrd --initrd ./\n```\n\nIf you don't have KVM support (such as when running inside a virtual machine), pass the `-W` option to `kraft run` to disable virtualization support:\n\n```console\nkraft run -W --target wamr-qemu-x86_64-initrd --initrd ./\n```\n\nWhen left without the `--target` argument, you'll be queried for the desired target from the list.\n\nRunning it will print a \"Hello, World!\" message by executing the `rootfs/main.wasm` file.\n\n## Work with the Basic Build \u0026 Run Toolchain (Advanced)\n\nYou can set up, configure, build and run the application from grounds up, without using the companion tool `kraft`.\n\n### Quick Setup (aka TLDR)\n\nFor a quick setup, run the commands below.\nNote that you still need to install the [requirements](#requirements).\n\nFor building and running everything for `x86_64`, follow the steps below:\n\n```console\ngit clone https://github.com/unikraft/app-wamr wamr\ncd wamr/\n./scripts/setup.sh\nwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.py\nchmod a+x scripts/generate.py\n./scripts/generate.py\n./scripts/build/make-qemu-x86_64-9pfs.sh\n./scripts/run/qemu-x86_64-9pfs.sh\n```\n\nThis will configure, build and run the `main.wasm` file via Wamr.\nYou can see how to test it in the [running section](#run).\n\nThe same can be done for `AArch64`, by running the commands below:\n\n```console\ngit clone https://github.com/unikraft/app-wamr wamr\ncd wamr/\n./scripts/setup.sh\nwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.py\nchmod a+x scripts/generate.py\n./scripts/generate.py\n./scripts/build/make-qemu-arm64-9pfs.sh\n./scripts/run/qemu-arm64-9pfs.sh\n```\n\nSimilar to the `x86_64` build, this will start the `main.wasm` file via Wamr.\nInformation about every step is detailed below.\n\n### Requirements\n\nIn order to set up, configure, build and run wamr on Unikraft, the following packages are required:\n\n* `build-essential` / `base-devel` / `@development-tools` (the meta-package that includes `make`, `gcc` and other development-related packages)\n* `sudo`\n* `flex`\n* `bison`\n* `git`\n* `wget`\n* `uuid-runtime`\n* `qemu-system-x86`\n* `qemu-kvm`\n* `sgabios`\n\nGCC \u003e= 8 is required to build wamr on Unikraft.\n\nOn Ubuntu/Debian or other `apt`-based distributions, run the following command to install the requirements:\n\n```console\n$ apt-get install -y --no-install-recommends \\\n  build-essential \\\n  sudo \\\n  libncurses-dev \\\n  libyaml-dev \\\n  flex \\\n  bison \\\n  git \\\n  wget \\\n  uuid-runtime \\\n  qemu-kvm \\\n  qemu-system-x86 \\\n  sgabios\n```\n\n### Set Up\n\nThe following repositories are required for wamr:\n\n* The application repository (this repository): [`app-wamr`](https://github.com/unikraft/app-wamr)\n* The Unikraft core repository: [`unikraft`](https://github.com/unikraft/unikraft)\n* Library repositories:\n  * The wamr \"library\" repository: [`lib-wamr`](https://github.com/unikraft/lib-wamr)\n  * The standard C library: [`lib-musl`](https://github.com/unikraft/lib-musl)\n  * The networking stack library: [`lib-lwip`](https://github.com/unikraft/lib-lwip)\n\nFollow the steps below for the setup:\n\n  1. First clone the [`app-wamr` repository](https://github.com/unikraft/app-wamr) in the `wamr/` directory:\n\n     ```console\n     git clone https://github.com/unikraft/app-wamr wamr\n     ```\n\n     Enter the `wamr/` directory:\n\n     ```console\n     cd wamr/\n\n     ls -aF\n     ```\n\n     This will print the contents of the repository:\n\n     ```text\n     Makefile  Makefile.uk  README.md  defconfigs/  kraft.yaml  rootfs/  scripts/\n     ```\n\n  1. While inside the `wamr/` directory, clone all required repositories by using the `setup.sh` script:\n\n     ```console\n     ./scripts/setup.sh\n     ```\n\n  1. Use the `tree` command to inspect the contents of the `workdir/` directory:\n\n     ```console\n     tree -F -L 2 workdir/\n     ```\n\n     The layout of the `workdir/` directory should look something like this:\n\n     ```text\n       workdir/\n       |-- libs/\n       |   |-- lwip/\n       |   |-- musl/\n       |   `-- wamr/\n       `-- unikraft/\n           |-- arch/\n           |-- Config.uk\n           |-- CONTRIBUTING.md\n           |-- COPYING.md\n           |-- include/\n           |-- lib/\n           |-- Makefile\n           |-- Makefile.uk\n           |-- plat/\n           |-- README.md\n           |-- support/\n           `-- version.mk\n\n     9 directories, 7 files\n     ```\n\n### Scripted Building and Running\n\nTo make it easier to build, run and test different configurations, the repository provides a set of scripts that do everything required.\nThese are scripts used for building different configurations of Duktape and for running these with all the requirements behind the scenes.\n\nFirst of all, grab the [`generate.py` script](https://github.com/unikraft/app-testing/blob/staging/scripts/generate.py) and place it in the `scripts/` directory by running:\n\n```console\nwget https://raw.githubusercontent.com/unikraft/app-testing/staging/scripts/generate.py -O scripts/generate.py\nchmod a+x scripts/generate.py\n```\n\nNow, run the `generate.py` script.\nYou must run it in the root directory of this repository:\n\n```console\n./scripts/generate.py\n```\n\nThe scripts (as shell scripts) are now generated in `scripts/build/` and `scripts/run/`:\n\n```text\nscripts/\n|-- build/\n|   |-- kraft-kvm-x86_64.sh*\n|   |-- make-fc-arm64-initrd.sh*\n|   |-- make-fc-arm64.sh*\n|   |-- make-fc-x86_64-initrd.sh*\n|   |-- make-fc-x86_64.sh*\n|   |-- make-qemu-arm64-9pfs.sh*\n|   |-- make-qemu-arm64-initrd.sh*\n|   |-- make-qemu-arm64.sh*\n|   |-- make-qemu-x86_64-9pfs.sh*\n|   |-- make-qemu-x86_64-initrd.sh*\n|   `-- make-qemu-x86_64.sh*\n|-- generate.py*\n|-- run/\n|   |-- fc-arm64-initrd.json\n|   |-- fc-arm64-initrd.sh*\n|   |-- fc-arm64.json\n|   |-- fc-arm64.sh*\n|   |-- fc-x86_64-initrd.json\n|   |-- fc-x86_64-initrd.sh*\n|   |-- fc-x86_64.json\n|   |-- fc-x86_64.sh*\n|   |-- kraft-kvm-x86_64.sh*\n|   |-- qemu-arm64-9pfs.sh*\n|   |-- qemu-arm64-initrd.sh*\n|   |-- qemu-arm64.sh*\n|   |-- qemu-x86_64-9pfs.sh*\n|   |-- qemu-x86_64-initrd.sh*\n|   `-- qemu-x86_64.sh*\n|-- run.yaml\n`-- setup.sh*\n```\n\nThey are shell scripts, so you can use an editor or a text viewer to check their contents:\n\n```console\ncat scripts/run/fc-x86_64-initrd.sh\n```\n\nNow, invoke each script to build and run the application.\nA sample build and run set of commands is:\n\n```console\n./scripts/build/make-qemu-x86_64-9pfs.sh\n./scripts/run/qemu-x86_64-9pfs.sh\n```\n\nNote that Firecracker only works with initrd (not 9pfs).\nAnd Firecracker networking is not yet upstream.\n\n## Detailed Steps\n\n### Configure\n\nConfiguring, building and running a Unikraft application depends on our choice of platform and architecture.\nCurrently, supported platforms are QEMU (KVM), Xen and linuxu.\nQEMU (KVM) is known to be working, so we focus on that.\n\nSupported architectures are x86_64 and AArch64.\n\nUse the corresponding the configuration files (`defconfigs/*`), according to your choice of platform and architecture.\n\n#### QEMU x86_64\n\nUse the `defconfigs/qemu-x86_64-9pfs` configuration file together with `make defconfig` to create the configuration file:\n\n```console\nUK_DEFCONFIG=$(pwd)/defconfigs/qemu-x86_64-9pfs make defconfig\n```\n\nThis results in the creation of the `.config` file:\n\n```console\nls .config\n.config\n```\n\nThe `.config` file will be used in the build step.\n\n#### QEMU AArch64\n\nUse the `defconfigs/qemu-arm64-9pfs` configuration file together with `make defconfig` to create the configuration file:\n\n```console\nUK_DEFCONFIG=$(pwd)/defconfigs/qemu-arm64-9pfs make defconfig\n```\n\nSimilar to the x86_64 configuration, this results in the creation of the `.config` file that will be used in the build step.\n\n### Build\n\nBuilding uses as input the `.config` file from above, and results in a unikernel image as output.\nThe unikernel output image, together with intermediary build files, are stored in the `workdir/build/` directory.\n\n#### Clean Up\n\nBefore starting a build on a different platform or architecture, you must clean up the build output.\nThis may also be required in case of a new configuration.\n\nCleaning up is done with 3 possible commands:\n\n* `make clean`: cleans all actual build output files (binary files, including the unikernel image)\n* `make properclean`: removes the entire `workdir/build/` directory\n* `make distclean`: removes the entire `workdir/build/` directory **and** the `.config` file\n\nTypically, you would use `make properclean` to remove all build artifacts, but keep the configuration file.\n\n#### QEMU x86_64\n\nBuilding for QEMU x86_64 assumes you did the QEMU x86_64 configuration step above.\nBuild the Unikraft Wamr image for QEMU x86_64 by using the command below:\n\n```console\nmake -j $(nproc)\n```\n\nYou will see a list of all the files generated by the build system:\n\n```text\n[...]\n  LD      wamr_qemu-x86_64.dbg\n  UKBI    wamr_qemu-x86_64.dbg.bootinfo\n  SCSTRIP wamr_qemu-x86_64\n  GZ      wamr_qemu-x86_64.gz\nmake[1]: Leaving directory 'wamr/workdir/unikraft'\n```\n\nAt the end of the build command, the `wamr_qemu-x86_64` unikernel image is generated.\nThis image is to be used in the run step.\n\n#### QEMU AArch64\n\nIf you had configured and build a unikernel image for another platform or architecture (such as x86_64) before, then:\n\n1. Do a cleanup step with `make properclean`.\n\n1. Configure for QEMU AAarch64, as shown above.\n\n1. Follow the instructions below to build for QEMU AArch64.\n\nBuilding for QEMU AArch64 assumes you did the QEMU AArch64 configuration step above.\nBuild the Unikraft Wamr image for QEMU AArch64 by using the same command as for x86_64:\n\n```console\nmake -j $(nproc)\n```\n\nSimilar to building for x86_64, you will see a list of the files generated by the build system.\n\n```text\n[...]\n  LD      wamr_qemu-arm64.dbg\n  UKBI    wamr_qemu-arm64.dbg.bootinfo\n  SCSTRIP wamr_qemu-arm64\n  GZ      wamr_qemu-arm64.gz\nmake[1]: Leaving directory 'wamr/workdir/unikraft\n```\n\nSimilarly to x86_64, at the end of the build command, the `wamr_qemu-arm64` unikernel image is generated.\nThis image is to be used in the run step.\n\n### Run\n\n#### QEMU x86_64\n\nTo run the QEMU x86_64 build, use `run-qemu-x86_64-9pfs.sh`:\n\n```console\n./scripts/generate.py\n./scripts/run/qemu-x86_64-9pfs.sh\n```\n\nThis will run the `rootfs/main.wasm` file with Wamr:\n\n```text\nPowered by\no.   .o       _ _               __ _\nOo   Oo  ___ (_) | __ __  __ _ ' _) :_\noO   oO ' _ `| | |/ /  _)' _` | |_|  _)\noOo oOO| | | | |   (| | | (_) |  _) :_\n OoOoO ._, ._:_:_,\\_._,  .__,_:_, \\___)\n             Prometheus 0.14.0~14b1ee3d\nHello world!\nbuf ptr: 0x400002b0\nbuf: 1234\n```\n\n#### QEMU AArch64\n\nTo run the AArch64 build, use `run-qemu-aarch64-9pfs.sh`:\n\n```console\n./scripts/generate.py\n./scripts/run/qemu-arm64-9pfs.sh\n```\n\nSame as above, this will run the `rootfs/main.wasm` file with Wamr.\n\n### Building and Running with initrd\n\nThe examples above use 9pfs as the filesystem interface.\nClean up the previous configuration, use the initrd configuration and build the unikernel by using the commands:\n\n```console\n./scripts/generate.py\n./scripts/build/make-qemu-x86_64-initrd.sh\n```\n\nTo run the QEMU x86_64 initrd build, use the `qemu-x86_64-initrd.sh` script:\n\n```console\n./scripts/run/qemu-x86_64-initrd.sh\n```\n\nThe commands for AArch64 are similar:\n\n```console\n./scripts/build/make-qemu-arm64-initrd.sh\n./scripts/run/qemu-arm64-initrd.sh\n```\n\n### Building and Running with Firecracker\n\n[Firecracker](https://firecracker-microvm.github.io/) is a lightweight VMM (*virtual machine manager*) that can be used as more efficient alternative to QEMU.\n\nConfigure and build commands are similar to a QEMU-based build with an initrd-based filesystem:\n\n```console\n./scripts/build/make-fc-x86_64-initrd.sh\n```\n\nTo use Firecraker, you need to download a [Firecracker release](https://github.com/firecracker-microvm/firecracker/releases).\nYou can use the commands below to make the `firecracker-x86_64` executable from release v1.4.0 available globally in the command line:\n\n```console\ncd /tmp \nwget https://github.com/firecracker-microvm/firecracker/releases/download/v1.4.0/firecracker-v1.4.0-x86_64.tgz\ntar xzf firecracker-v1.4.0-x86_64.tgz \nsudo cp release-v1.4.0-x86_64/firecracker-v1.4.0-x86_64 /usr/local/bin/firecracker-x86_64\n```\n\nTo run a unikernel image, you need to configure a JSON file.\nThis is the `scripts/run/fc-x86_64-initrd.json` file.\nThis configuration file is uses as part of the run command:\n\n```console\n./scripts/run/fc-x86_64-initrd.sh\n```\n\nSame as running with QEMU, the application will start:\n\n```text\nPowered by\no.   .o       _ _               __ _\nOo   Oo  ___ (_) | __ __  __ _ ' _) :_\noO   oO ' _ `| | |/ /  _)' _` | |_|  _)\noOo oOO| | | | |   (| | | (_) |  _) :_\n OoOoO ._, ._:_:_,\\_._,  .__,_:_, \\___)\n             Prometheus 0.14.0~14b1ee3d\nHello world!\nbuf ptr: 0x400002b0\nbuf: 1234\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikraft%2Fapp-wamr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funikraft%2Fapp-wamr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funikraft%2Fapp-wamr/lists"}