GitHub - tufteddeer/gleam-webassembly: A modified Gleam compiler to translate Gleam to WebAssembly

This is a fork of the Gleam language compiler.

This compiler can be used to translate Gleam programs into WebAssembly binaries.

An example application showcasing the performance improvement gained by compiling Gleam to WebAssembly instead of JavaScript is available here (source).

A list containing all implemented features of the Gleam language is included below.

Key features are:

a time and space efficient implementation of generics and custom types (based on work by Lutze, Schuster, Brachthäuser)
tail recursion
imports of JavaScript and WebAssembly functions using the @external attribute
exporting of functions using the new @wasm_export attribute

The Gleam version is 1.9.1.

Most of the code is in the compiler-core/src/wasm.rs file and the compiler-core/src/webassembly module

In addition to the incomplete features below, future work should focus on restructuring the translation process. While the current version is working, it could probably be improved by adding more intermediary steps to perform transformations on the AST before translating it to wasm.

You may also be interested in previous work:

https://github.com/DanielleMaywood/fyp-gleam

Process overview

Changes are made primarily at the backend. The generated AST first undergoes monomorphization, so generic types can be mostly ignored in the next steps.

After some extra work to gather information on Tuples, Custom Types and anonymous functions, the AST is translated to WebAssembly. Most of this preparation should probably be refactored so that is creates additional, intermediary ASTs because the current approach (AST + additional infos in other data structures) is hard to extend and maintain.

The implementation allows including .wat files, which may contain handwritten or generated .wasm code from other sources. This is useful to access runtime features or WebAssembly instructions and could be useful to implement a standard library targeting WebAssembly.

The result is a single .wasm file that can be executed by the runtime.

The implementation lacks support for multiple Gleam modules/files. My plan was to support this by translating each module into a separate .wasm module and merge them at the end (like it's done with external .wasm modules). While this should still be possible, it would require some workarrounds because WebAssembly has limited support regarding type exports. Manually copying the types to every module and deduplicating after the merge might work though.

Features

The following aspects of the Gleam language tour are at least partially supported

Feature	Status	Bemerkung
Hello World	✔️	Only in JS-Engine using `console.log` with @external, no stlib support
Ints	✅
Floats	✅
Equality	✔️	Not for Tuples (implementation would be similar to custom types)
Strings	✔️	Only in Engines supporting JS builtins. No escape sequences yet
Bools	✅
Assignments	✅
Discard patterns	✅
Blocks	✅
Lists	✅
Constants	✔️	Just Int and Float
Functions	✅
Higher order functions	✅
Anonymous functions	✔️	Immediately calling a `fn` expression is not implemented yet
Function captures	✅
Generic functions	✔️	No polymorphic recursion
Pipelines	✔️	Not for `echo`
Case expressions	✔️	Single subject, no guards, no alternative patterns
Variable patterns	✅
String patterns	✅
List patterns	✅
Recursion	✅
Tail calls	✅	Tail calls are optimized
List recursion	✅
Tuples	✔️	As long as they are not generic used together with records
Custom Types	✔️	No cyclic references
Records	✅
Record accessors	✅
Record pattern matching	✔️	Only in `case` patterns
Record updates	✅
Generic custom types	✅
Nil	✅
Todo/Panic	✔️	Without message, since strings and printing to stdout is not supported everywhere
Externals	✅	Currently, functions having the @external attribute must provide a default implementation (`{panic}` is sufficient)

Usage

If you are not familiar with Gleam, checkout tutorial.

Use the following gleam.toml:

name = "yourprojectname"
version = "1.0.0"

[dependencies]

[dev-dependencies]

[webassembly]
runtime = "deno"

Please note that dependencies and tests are currently not supported. Remove them. Your project must consist of a single .gleam file with at least the main function (pub fn main).

In the next steps, we assume the current working directory is the Gleam project root.

The WebAssembly artifacts are in build/dev/webassembly/<package>.

Use GLEAM_LOG=trace to see all log messages.

The easiest way to use the compiler and execute the programs is with Docker or Nix because they include the Deno runtime and wasm-tools, which is required for some features.

When you use gleam run it will print the return value of the main function.

For advanced features like importing JavaScript or WebAssembly-Functions or exporting functions from the module, see the examples here and here

Using docker

docker run -v ./:/src -it ghcr.io/tufteddeer/gleam-webassembly:webassembly bash -c "gleam run --target webassembly"

Using cargo

Get the sourcecode.

You can build the project like any other Rust application. Then, use the binary like:

gleam run --target webassembly

or point cargo to the source directory and use cargo run

cargo run --manifest-path <path/to/compiler/src>/Cargo.toml -- build --target webassembly

Using nix

Get the sourcecode. Inside the Gleam project, use

nix run <path/to/compiler/src> -- run --target webassembly

todo: nix run https://github.com/tufteddeer/gleam-webassembly -- run --target webassembly would be nicer, but since the repo is currently private we must fetch the source ourselves

Tests

Make sure you have Rust, Deno and all dependencies installed (further down this page)

cd test-wasm-js-parity/testrunner/
deno test -A

This will build the compiler and execute all test cases contained in test-wasm-js-parity/gleam to ensure equal behavior between Gleam compiled to JS and Wasm.

Supported targets

tl;dr: use Deno or the browser

The best supported targets are Deno and the browser (recent Chrome versions). Builds made for Deno are compatible with the browser.

The runtime (default: Deno) has to be configured in the gleam.toml file, not via 'gleam run --runtime'. While this might work with different JS based runtimes, it won't work with others like Wasmtime. This is because the selected runtime affects code generation (e.g JS String builtin imports) and must be known when building the binary.

[webassembly]
runtime = "deno"

Wasmtime is supported, as long as no strings are used.

Hosts executing Wasm Component Model binaries are barely supported and only as long as the used types are limited to integer and float values (example). To build modules to be used with the component model, use 'componentmodel' as runtime.

Requirements

wasm-merge, Version 123 or compatible
a WebAssembly runtime, preferably Deno

Versions

The following versions where used to develop and test the project

Gleam 1.9.1
wasmtime 31
wasm-merge 123
wasm-tools 1.229
Chrome 137
Deno 2.2
Rust 1.87

Changes not directly related to WebAssembly

a nix flake to build Gleam including a development shell with Deno, Wasmtime and some Wasm tools needed in compatible versions
a Docker image with all required tools to try Gleam with WebAssembly
gleam run on Deno prints the return value of the main function for easier testing
springled some #[allow(clippy::XXX)] over upstream code to suppress new lints
ci: clippy is pinned to 1.87 so it does not surprise me with new lints every few weeks
pinned gleam stdlib to a version that supports gleam 1.9.1 in some test projects since newer versions require a newer gleam binary, disabled some tests with the same problem

Gleam is a friendly language for building type-safe systems that scale! For more information see the website.

Sponsors

Gleam is kindly supported by its sponsors. If you would like to support Gleam please consider sponsoring its development on GitHub.

Thank you to our sponsors! Gleam would not be possible without you.

Name		Name	Last commit message	Last commit date
Latest commit History 8,880 Commits
.github		.github
.vscode		.vscode
.well-known		.well-known
bin		bin
changelog		changelog
compiler-cli		compiler-cli
compiler-core		compiler-core
compiler-wasm		compiler-wasm
containers		containers
docs		docs
gleam-bin		gleam-bin
gleam-wasm-features		gleam-wasm-features
images		images
test-community-packages		test-community-packages
test-helpers-rs		test-helpers-rs
test-output		test-output
test-package-compiler		test-package-compiler
test-project-compiler		test-project-compiler
test-wasm-js-parity		test-wasm-js-parity
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Cross.toml		Cross.toml
LICENCE		LICENCE
Makefile		Makefile
README.md		README.md
RELEASE.md		RELEASE.md
deny.toml		deny.toml
flake.lock		flake.lock
flake.nix		flake.nix

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Process overview

Features

Usage

Using docker

Using cargo

Using nix

Tests

Supported targets

Requirements

Versions

Changes not directly related to WebAssembly

Sponsors

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Process overview

Features

Usage

Using docker

Using cargo

Using nix

Tests

Supported targets

Requirements

Versions

Changes not directly related to WebAssembly

Sponsors

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages