• Stars
    star
    2,240
  • Rank 20,569 (Top 0.5 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created over 3 years ago
  • Updated 20 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

JS to WebAssembly toolchain

Javy

A JavaScript to Webassembly toolchain

A Bytecode Alliance project

Build status zulip chat

About this repo

Introduction: Run your JavaScript on WebAssembly. Javy takes your JavaScript code, and executes it in a WebAssembly embedded JavaScript runtime. Javy can create very small Wasm modules in the 1 to 16 KB range with use of dynamic linking. The default static linking produces modules that are at least 869 KB in size.

Runtime requirements

When running the official Javy binary on Linux, glibc 2.31 or greater must be available. You may need to update the version of your operating system if you are using an older version of glibc.

Contributing

We welcome feedback, bug reports and bug fixes. We're also happy to discuss feature development but please discuss the features in an issue before contributing.

Read our contribution documentation for additional information on contributing to Javy.

Build

  • rustup
  • Stable Rust (rustup install stable && rustup default stable)
  • wasm32-wasi, can be installed via rustup target add wasm32-wasi
  • cmake, depending on your operating system and architecture, it might not be installed by default. On Mac it can be installed with homebrew via brew install cmake
  • Rosetta 2 if running MacOS on Apple Silicon, can be installed via softwareupdate --install-rosetta

Development

  • wasmtime-cli, can be installed via cargo install wasmtime-cli (required for cargo-wasi)
  • cargo-wasi, can be installed via cargo install cargo-wasi
  • wizer, can be installed via cargo install wizer --all-features
  • cargo-hack, can be installed via cargo +stable install cargo-hack --locked

Building

$ cargo build -p javy-core --target=wasm32-wasi -r
$ cargo build -p javy-cli -r

Alternatively you can run cargo install --path crates/cli to install the Javy CLI globally.

Compiling to WebAssembly

Define your JavaScript like:

// Read input from stdin
const input = readInput();
// Call the function with the input
const result = foo(input);
// Write the result to stdout
writeOutput(result);

// The main function.
function foo(input) {
    return { foo: input.n + 1, newBar: input.bar + "!" };
}

// Read input from stdin
function readInput() {
    const chunkSize = 1024;
    const inputChunks = [];
    let totalBytes = 0;

    // Read all the available bytes
    while (1) {
        const buffer = new Uint8Array(chunkSize);
        // Stdin file descriptor
        const fd = 0;
        const bytesRead = Javy.IO.readSync(fd, buffer);

        totalBytes += bytesRead;
        if (bytesRead === 0) {
            break;
        }
        inputChunks.push(buffer.subarray(0, bytesRead));
    }

    // Assemble input into a single Uint8Array
    const { finalBuffer } = inputChunks.reduce((context, chunk) => {
        context.finalBuffer.set(chunk, context.bufferOffset);
        context.bufferOffset += chunk.length;
        return context;
    }, { bufferOffset: 0, finalBuffer: new Uint8Array(totalBytes) });

    return JSON.parse(new TextDecoder().decode(finalBuffer));
}

// Write output to stdout
function writeOutput(output) {
    const encodedOutput = new TextEncoder().encode(JSON.stringify(output));
    const buffer = new Uint8Array(encodedOutput);
    // Stdout file descriptor
    const fd = 1;
    Javy.IO.writeSync(fd, buffer);
}

Create a WebAssembly binary from your JavaScript by:

javy compile index.js -o destination/index.wasm

For more information on the commands you can run javy --help

You can then execute your WebAssembly binary using a WebAssembly engine:

$ echo '{ "n": 2, "bar": "baz" }' | wasmtime index.wasm
{"foo":3,"newBar":"baz!"}%   

Invoking Javy-generated modules programatically

Javy-generated modules are by design WASI only and follow the command pattern. Any input must be passed via stdin and any output will be placed in stdout. This is especially important when invoking Javy modules from a custom embedding.

In a runtime like Wasmtime, wasmtime-wasi can be used to set the input and retrieve the output.

Creating and using dynamically linked modules

An important use for Javy is for when you may want or need to generate much smaller Wasm modules. Using the -d flag when invoking Javy will create a dynamically linked module which will have a much smaller file size than a statically linked module. Statically linked modules embed the JS engine inside the module while dynamically linked modules rely on Wasm imports to provide the JS engine. Dynamically linked modules have special requirements that statically linked modules do not and will not execute in WebAssembly runtimes that do not meet these requirements.

To successfully instantiate and run a dynamically linked Javy module, the execution environment must provide a javy_quickjs_provider_v1 namespace for importing that links to the exports provided by the javy_quickjs_provider.wasm module. Dynamically linked modules cannot be instantiated in environments that do not provide this import.

Dynamically linked Javy modules are tied to QuickJS since they use QuickJS's bytecode representation.

Obtaining the QuickJS provider module

The javy_quickjs_provider.wasm module is available as an asset on the Javy release you are using. It can also be obtained by running javy emit-provider -o <path> to write the module into <path>.

Creating and running a dynamically linked module on the CLI

$ echo 'console.log("hello world!");' > my_code.js
$ javy compile -d -o my_code.wasm my_code.js
$ javy emit-provider -o provider.wasm
$ wasmtime run --preload javy_quickjs_provider_v1=provider.wasm my_code.wasm
hello world!

Using quickjs-wasm-rs to build your own toolchain

The quickjs-wasm-rs crate that is part of this project can be used as part of a Rust crate targeting Wasm to customize how that Rust crate interacts with QuickJS. This may be useful when trying to use JavaScript inside a Wasm module and Javy does not fit your needs as quickjs-wasm-rs contains serializers that make it easier to send structured data (for example, strings or objects) between host code and Wasm code.

Releasing

  1. Update the root Cargo.toml with the new version
  2. Create a tag for the new version like v0.2.0
git tag v0.2.0
git push origin --tags
  1. Create a new release from the new tag in github here.
  2. A GitHub Action will trigger for publish.yml when a release is published (i.e. it doesn't run on drafts), creating the artifacts for downloading.

More Repositories

1

wasmtime

A fast and secure runtime for WebAssembly
Rust
15,075
star
2

wasm-micro-runtime

WebAssembly Micro Runtime (WAMR)
C
4,925
star
3

lucet

Lucet, the Sandboxing WebAssembly Compiler.
Rust
4,065
star
4

cranelift

Cranelift code generator
2,488
star
5

rustix

Safe Rust bindings to POSIX-ish APIs
Rust
1,424
star
6

wasm-tools

CLI and Rust libraries for low-level manipulation of WebAssembly modules
Rust
1,270
star
7

wit-bindgen

A language binding generator for WebAssembly interface types
Rust
1,024
star
8

wizer

The WebAssembly Pre-Initializer
Rust
932
star
9

wasmtime-go

Go WebAssembly runtime powered by Wasmtime
Go
771
star
10

cap-std

Capability-oriented version of the Rust standard library
Rust
646
star
11

cranelift-jit-demo

JIT compiler and runtime for a toy language, using Cranelift
Rust
636
star
12

jco

JavaScript toolchain for working with WebAssembly Components
Rust
598
star
13

cargo-component

A Cargo subcommand for creating WebAssembly components based on the component model proposal.
Rust
468
star
14

cargo-wasi

A lightweight Cargo subcommand to build Rust code for the `wasm32-wasi` target
Rust
439
star
15

wasmtime-dotnet

.NET embedding of Wasmtime https://bytecodealliance.github.io/wasmtime-dotnet/
C#
409
star
16

wasmtime-py

Python WebAssembly runtime powered by Wasmtime
Python
385
star
17

wasi-rs

Experimental WASI API bindings for Rust
Rust
254
star
18

ComponentizeJS

JS -> WebAssembly Component
Rust
213
star
19

wasi.dev

JavaScript
209
star
20

regalloc2

A new register allocator
Rust
200
star
21

registry

WebAssembly Registry (Warg)
Rust
189
star
22

wasmparser

A simple event-driven library for parsing WebAssembly binary files
178
star
23

wasmtime-demos

Historical and dated demos for Wasmtime usage and WASI content
C#
153
star
24

WASI-Virt

Virtual implementations of WASI APIs
Rust
139
star
25

componentize-py

Rust
138
star
26

wrpc

Wasm component-native RPC framework
Rust
114
star
27

wat

Rust WAT and WAST parser (WebAssembly Text Format)
113
star
28

wac

WebAssembly Composition (WAC) tooling
Rust
107
star
29

regalloc.rs

Modular register allocator algorithms
Rust
106
star
30

wasmtime-rb

Ruby WebAssembly runtime powered by Wasmtime
Rust
95
star
31

spidermonkey-wasm-rs

Rust
87
star
32

wasmtime-cpp

C++
81
star
33

preview2-prototyping

Polyfill adapter for preview1-using wasm modules to call preview2 functions.
Rust
79
star
34

wasm-interface-types

Raw Rust toolchain support for Wasm Interface Types
Rust
70
star
35

component-docs

Documentation around creating and using WebAssembly Components
Rust
68
star
36

sightglass

A benchmark suite and tool to compare different implementations of the same primitives.
C
67
star
37

wasm-tools-go

WebAssembly + Component Model tools for Go
Go
60
star
38

rfcs

RFC process for Bytecode Alliance projects
60
star
39

StarlingMonkey

The StarlingMonkey JS runtime
C++
58
star
40

wasm-pkg-tools

Rust
56
star
41

target-lexicon

Target "triple" support
Rust
48
star
42

wit-deps

WIT dependency manager
Rust
47
star
43

userfaultfd-rs

Rust bindings for the Linux userfaultfd functionality
Rust
43
star
44

wasi-nn

High-level bindings for wasi-nn system calls
CSS
42
star
45

system-interface

Extensions to the Rust standard library
Rust
41
star
46

waffle

Wasm Analysis Framework For Lightweight Experiments
Rust
34
star
47

wasmprinter

Rust library to print a WebAssembly binary to its textual format
32
star
48

wasm-component-ld

Command line linker for creating WebAssembly components
Rust
31
star
49

meetings

Python
28
star
50

wamr-rust-sdk

Rust
28
star
51

wasm-score

A benchmark for standalone WebAssembly
C
26
star
52

weval

the WebAssembly partial evaluator
Rust
25
star
53

spidermonkey-wasm-build

Utilities to compile SpiderMonkey to wasm32-wasi
JavaScript
24
star
54

vscode-wit

Visual Studio Code extension to recognize and highlight the WebAssembly Interface Type (WIT) IDL.
TypeScript
22
star
55

filecheck

Library for writing tests for utilities that read text files and produce text output
Rust
21
star
56

componentize-dotnet

Tooling for creating WebAssembly components from C#
C#
17
star
57

cranelift.vim

Vim editor configuration for working with cranelift IR (clif) files
Vim Script
15
star
58

arf-strings

Encoding and decoding for ARF strings
C
13
star
59

SIG-Guest-Languages

Special Interest Group (SIG) whose goal is to investigate how best to integrate Wasm and components into dynamic programming language ecosystems in a way that feels native to those ecosystems.
13
star
60

SIG-Registries

11
star
61

governance

11
star
62

subscribe-to-label-action

A GitHub action that allows users to subscribe to a label and automatically get @'d when the label is applied
JavaScript
11
star
63

bytecodealliance.org

CSS
10
star
64

wasm-spec-interpreter

Rust bindings for the Wasm spec interpreter.
Rust
10
star
65

spidermonkey-wasi-embedding

Shell
9
star
66

wamr-app-framework

WebAssembly Micro Runtime Application Framework
C
9
star
67

wasm-parallel-gzip

Some example scripts for building a parallel compression/decompression tool for WebAssembly
Makefile
8
star
68

fs-set-times

Set filesystem timestamps
Rust
6
star
69

wasmtime-libfuzzer-corpus

libFuzzer corpus for our wasmtime fuzz targets
Shell
6
star
70

rust-oci-wasm

A Rust implementation of the OCI artifact specification for WebAssembly
Rust
6
star
71

arena-btree

Rust
6
star
72

cm-go

Go
6
star
73

sig-embedded

6
star
74

wamr-python

Python
6
star
75

wamr.dev

The WAMR homepage
HTML
5
star
76

wasmtime.dev

The Wasmtime homepage
CSS
4
star
77

libc-test

Mirror of git://nsz.repo.hu:49100/repo/libc-test (see https://wiki.musl-libc.org/libc-test.html for more information)
C
4
star
78

actions

GitHub actions to setup wasm-tools and wasmtime
TypeScript
3
star
79

wasmtime-wasi-nn

2
star
80

cranelift.dev

CSS
1
star
81

label-messager-action

Automatically leave a message when an issue or pull request has a certain label
JavaScript
1
star
82

wasm-ml-meetings

Informal working group for machine learning and WebAssembly, especially wasi-nn
1
star