Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mewz-project/mewz

A unikernel designed specifically for running Wasm applications and compatible with WASI
https://github.com/mewz-project/mewz

kernel unikernel wasm webassembly webassembly-runtime zig

Last synced: about 22 hours ago
JSON representation

A unikernel designed specifically for running Wasm applications and compatible with WASI

Host: GitHub
URL: https://github.com/mewz-project/mewz
Owner: mewz-project
License: gpl-3.0
Created: 2023-12-28T05:40:06.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2024-12-20T15:25:37.000Z (23 days ago)
Last Synced: 2025-01-04T10:38:15.090Z (8 days ago)
Topics: kernel, unikernel, wasm, webassembly, webassembly-runtime, zig
Language: Zig
Homepage:
Size: 1.21 MB
Stars: 547
Watchers: 6
Forks: 15
Open Issues: 10
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-zig - Mewz🗒️A unikernel designed specifically for running Wasm applications and compatible with WASI

README

[![CI](https://github.com/mewz-project/mewz/actions/workflows/ci.yaml/badge.svg)](https://github.com/mewz-project/mewz/actions/workflows/ci.yaml)

# Mewz

![](img/mewz-logo.png)

Mewz is a unikernel designed specifically for running Wasm applications and compatible with WASI.

## What's new with Mewz

There are now various Wasm runtimes, but they operate on general-purpose operating systems such as Linux or Windows.

Mewz is **a specialized kernel designed for running Wasm**. Mewz runs a single Wasm application within the kernel by linking it together during the build process with the Wasm application. (A kernel composed in this manner is commonly referred to as a **unikernel**.) In this way, Mewz provides **the minimal required features and environment for executing Wasm**.

![](img/mewz-architecture.png)

## Quick Start

There are some example programs. Please check out [examples](https://github.com/Mewz-project/Mewz/tree/main/examples).

### Option1: Docker

We prepare for a Docker image that has a environment for running Mewz.

```sh
curl -o helloworld.wat https://raw.githubusercontent.com/Mewz-project/Wasker/main/helloworld.wat
docker run -v .:/volume ghcr.io/mewz-project/mewz helloworld.wat
```

This image internally run [Wasker](https://github.com/mewz-project/wasker), build Mewz, and run it on QEMU.

![](img/mewz-demo.gif)

### Option2: Dev Container

You can use Dev Container on GitHub Codespaces or your local VSCode.

To start Codespaces,

- Click Code -> Codespaces -> New codespace on this repository page.
- Wait for a while, then you can see VSCode on browser.
- Open terminal on VSCode

```sh
# On the Dev Container
git submodule update --init
curl -o helloworld.wat https://raw.githubusercontent.com/Mewz-project/Wasker/main/helloworld.wat
wasker helloworld.wat
zig build -Dapp-obj=wasm.o run
```

### Option3: Build from source

Compile a Wasm file into a native object file, using [Wasker](https://github.com/mewz-project/wasker). Follow the instruction [here](https://github.com/mewz-project/wasker#how-to-run-wasker).

Then, build Mewz and run it on QEMU with the following commands.

```sh
zig build -Dapp-obj= run
```

To use file systems, specify the directory by `-Ddir=`. See [examples/static_file_server](examples/static_file_server/).

> [!WARNING]
> This option makes an archive of the directory by `tar` and attach it to QEMU.

> [!NOTE]
> QEMU's port 1234 is mapped to localhost:1234.

## Development

### GDB

You can debug Mewz with GDB. When you run Mewz with QEMU, it listens on port 12345 for GDB. You can connect to it by just running GDB at the root of the repository as `.gdbinit` is already configured.

```sh
zig build -Dapp-obj= run
# In another terminal
gdb
```

`zig build debug` command prevent Mewz from booting up until GDB connects to it. This is useful when you want to debug the boot process.

```sh
zig build -Dapp-obj= debug
# In another terminal
gdb
```

### Run integration tests

```sh
zig bulid -Dtest=true run
```

## Current Status