Clone of Guile-Hoot (https://gitlab.com/spritely/guile-hoot) Scheme to WebAssembly compiler from the Spritely Institute
David Thompson 2ad7e501fd Document --user-imports flag in compile-wasm help output. | hai 6 días | |
---|---|---|
bin | hai 3 meses | |
design | hai 1 ano | |
doc | hai 4 semanas | |
examples | hai 6 meses | |
js-runner | hai 1 mes | |
lib | hai 1 semana | |
module | hai 6 días | |
reflect-js | hai 4 semanas | |
reflect-wasm | hai 1 mes | |
test | hai 6 días | |
.dir-locals.el | hai 1 mes | |
.gitignore | hai 5 meses | |
.gitlab-ci.yml | hai 4 meses | |
COPYING | hai 1 ano | |
LICENSE.txt | hai 1 ano | |
Makefile.am | hai 2 semanas | |
README.md | hai 4 meses | |
acinclude.m4 | hai 1 ano | |
bootstrap.sh | hai 1 ano | |
ci-manifest.scm | hai 1 ano | |
configure.ac | hai 2 meses | |
guix.scm | hai 2 meses | |
hoot.ase | hai 1 ano | |
hoot.png | hai 1 ano | |
pre-inst-env.in | hai 6 meses | |
size-metrics.scm | hai 10 meses | |
upload-ci-image | hai 8 meses |
Hoot is the codename for the Guile->WebAssembly project launched by the Spritely Institute. In addition to the compiler, Hoot contains a full WebAssembly toolchain with a WAT parser, an assembler, a disassembler, an interpreter, etc.
For a fuller picture of project status, including known limitations, see the "Status" section of our documentation..
Hoot aims to be an ahead-of-time compiler for all of R7RS-small Scheme to WebAssembly (aka Wasm). Hoot uses several Wasm extensions such as tail calls and garbage collection. The good news is that these extensions are already available in major browsers such as Mozilla Firefox and Google Chrome, and will soon be making their way into stable browser releases everywhere!
After completing R7RS-small support, we will move on to supporting all of Guile. We are keeping this end-goal in mind as we build the early deliverable.
Resulting code should all run on stock Guile. Currently, we require a Guile built from the main branch of Git as we have upstreamed several changes to Guile that have not yet been released.
In the end we expect to be able to compile Scheme programs to single WebAssembly files. To deploy on web browsers there is an associated JavaScript module. Some non-web targets are hosted by JavaScript implementations (e.g. node); those are similar to web browsers. Otherwise on WASI hosts we expect to have a WASI-specific support module eventually.
The minimal compiled module size is some tens of kilobytes, uncompressed. The auxiliary WebAssembly module to do impedance matching with JavaScript is about four kilobytes uncompressed, and the generic JS library is about 500 lines of unminified JS. As we implement more of Scheme, we hope to preserve this "small programs compile to small files" property, rather than having every compiled program include the whole of Guile's standard library.
We thought this project deserved a cute project name and mascot, and everyone at the time agreed an owl was nice, and Christine Lemmer-Webber had recently just drawn up this owl pixel art, and so it became the mascot. The name naturally flowed from there.
See the log file.
Note that at the time of writing, Hoot requires a development version of Guile. This may not be the case at your time of reading!
Below are system-specific instructions for installing Hoot.
Hoot is already available in Guix:
guix shell --pure guile-next guile-hoot
Hoot is available in Mac OS thanks to to Alex Conchillo Flaqué (whose instructions we are repeating here)!
Add the Guile Homebrew tap if you haven't already:
brew tap aconchillo/guile
If Guile is already installed with Homebrew, unlink it since we need a newer version:
brew unlink guile
Now, just install Hoot:
brew install guile-hoot
This will also install guile-next
, a bleeding edge version of Guile,
so it might take a while if there's no bottle available.
This is by far the easiest path because Guix does all the hard work for you.
First, clone the repository:
git clone https://gitlab.com/spritely/guile-hoot
cd guile-hoot
guix shell
./bootstrap.sh && ./configure && make
The guix shell
step will take a while to build because we're using a
custom version of Guile and a bleeding edge version of V8.
If everything worked okay you can now run make check
:
make check
Did everything pass? Cool! That means Hoot works on your machine!
Maybe you want to understand better what Hoot is actually doing, or maybe you want to hack on the version of Guile used for Hoot, or etc! This section is for you.
First, you need to build Guile from the main
branch.
Then you can clone and build this repo:
git clone https://gitlab.com/spritely/guile-hoot
cd guile-hoot
./bootstrap.sh && ./configure && make
To run the test suite against a production Wasm host, you will need a recent version of V8 or a V8 distribution such as NodeJS 22+. NodeJS is the easiest route.
Building V8 is annoying. You need to have depot_tools
installed;
see https://v8.dev/docs/source-code. Once you have that see
https://v8.dev/docs/build to build. You will end up with a d8
binary in out/x64.release
(if you are on an x86-64 platform).
If all that works you should be able to make check
:
make check
If you want to skip the V8 stuff, you can run the test suite against our own Wasm interpreter instead:
make check WASM_HOST=hoot
Hoot is a self-contained system, so the easiest way to try it is from the Guile REPL:
./pre-inst-env guile
From the Guile prompt, enter the following to evaluate the program
42
in Hoot's built-in Wasm interpreter:
scheme@(guile-user)> ,use (hoot reflect)
scheme@(guile-user)> (compile-value 42)
$5 = 42
More interestingly, Scheme procedures that live within the Wasm guest module can be called from Scheme as if they were host procedures:
scheme@(guile-user)> (define hello (compile-value '(lambda (x) (list "hello" x))))
scheme@(guile-user)> hello
$6 = #<hoot #<procedure>>
scheme@(guile-user)> (hello "world")
$7 = #<hoot ("hello" "world")>
Hoot also introduces the guild compile-wasm
subcommand which can be
used to compile a Scheme file to Wasm via the CLI or a build script:
echo 42 > 42.scm
./pre-inst-env guild compile-wasm -o 42.wasm 42.scm
To actually load 42.wasm
you could use the Hoot VM as mentioned
above or use a production WebAssembly implementation such as a web
browser. Hoot is compatible with Firefox 121+ and Chrome 119+.
WebKit-based browsers such as Safari are not currently compatible as
WebKit does not yet have the Wasm GC and tail call features that Hoot
relies upon.
The generated WebAssembly doesn't depend on a web browser/JavaScript,
but it does take some capabilities from the host system, such as the
BigInt implementation. For web browsers, these facilities are
provided by reflect.js
. This reflection
library requires two auxiliary WebAssembly modules:
1) reflect.wasm
, which is compiled from
reflect.wat
2) wtf8.wasm
, which is compiled from
wtf8.wat
.
See the manual for a more in-depth tutorial and full API documentation!
For quickly getting started with a new project, see
examples/project-template/README.md
for an explanation of how to use
our project template.
For more examples of using Hoot, check out a couple of our other repos:
Here's how to build a Docker image for use in GitLab CI. Guix produces the actual image, but skopeo is required to upload it to the GitLab container registry.
Get skopeo
:
guix shell skopeo
If this is your first time using the GitLab registry, you need to
login. This requires setting up a GitLab personal access
token with
read_api
and write_registry
permissions. Once you have a token,
run:
skopeo login registry.gitlab.com
Build and upload the image:
./upload-ci-image