119 lines
3.1 KiB
Markdown
119 lines
3.1 KiB
Markdown
phasm
|
|
=====
|
|
|
|
Elevator pitch
|
|
--------------
|
|
A programming language that looks like Python, handles like Haskell,
|
|
and compiles directly to WebAssembly.
|
|
|
|
Example
|
|
-------
|
|
|
|
From `examples/fib.py`:
|
|
|
|
```py
|
|
def helper(n: u64, a: u64, b: u64) -> u64:
|
|
if n < 1:
|
|
return a + b
|
|
|
|
return helper(n - 1, a + b, a)
|
|
|
|
@exported
|
|
def fib(n: u64) -> u64:
|
|
if n == 0:
|
|
return 0
|
|
|
|
if n == 1:
|
|
return 1
|
|
|
|
return helper(n - 1, 0, 1)
|
|
```
|
|
|
|
Compile to a WebAssembly text file:
|
|
```sh
|
|
python3 -m phasm examples/fib.py examples/fib.wat
|
|
```
|
|
|
|
Generate a WebAssembly binary file:
|
|
```sh
|
|
python wat2wasm.py examples/fib.wat -o examples/fib.wasm
|
|
```
|
|
|
|
Ready for including in your WebAssembly runtime!
|
|
|
|
Run `make examples` to start a local web server with some more examples. Each example has the source listed, as well as the compiled WebAssembly text.
|
|
|
|
Project state
|
|
-------------
|
|
This is a hobby project for now. Use at your own risk.
|
|
|
|
The parser, compiler and type checker are in a reasonably usable state.
|
|
|
|
What's still lacking is support for runtimes - notably, making it easier to get values in and out of the runtime.
|
|
For example, while Phasm supports a u32 type, when you get your value out, it will probably be a signed value.
|
|
And getting strings, structs, arrays and other combined values in and out requires manual work.
|
|
|
|
How to run
|
|
----------
|
|
You should only need make and python3. Currently, we're working with python3.12,
|
|
since we're using the python ast parser, it might not work on other versions.
|
|
|
|
To compile a Phasm file:
|
|
```sh
|
|
python3.12 -m phasm source.py output.wat
|
|
```
|
|
|
|
To run the examples:
|
|
```sh
|
|
make examples
|
|
```
|
|
|
|
To run the tests:
|
|
```sh
|
|
make test
|
|
```
|
|
|
|
To run the linting and type checking:
|
|
```sh
|
|
make lint typecheck
|
|
```
|
|
|
|
Gotcha's
|
|
--------
|
|
- When importing and exporting unsigned values to WebAssembly, they will become
|
|
signed, as WebAssembly has no native unsigned type. You may need to cast
|
|
or reinterpret them.
|
|
- Currently, Phasm files have the .py extension, which helps with syntax
|
|
highlighting, that might change in the future.
|
|
|
|
Contributing
|
|
------------
|
|
At this time, we're mostly looking for use cases for WebAssembly, other than to
|
|
compile existing C code and running them in the browser. The goal of WebAssembly
|
|
is to enable high-performance applications on web pages[5]. Though most people
|
|
seem to use it to have existing code run in the browser.
|
|
|
|
If you have a situation where WebAssembly would be useful for it's speed, we're
|
|
interested to see what you want to use it for.
|
|
|
|
Also, if you are trying out Phasm, and you're running into a limitation, we're
|
|
interested in a minimal test case that shows what you want to achieve and how
|
|
Phasm currently fails you.
|
|
|
|
We're also investigating using WASI - but that's still ongoing research. If you
|
|
have tips or ideas on that, we'd be interested.
|
|
|
|
Name origin
|
|
-----------
|
|
- p from python
|
|
- ha from Haskell
|
|
- asm from WebAssembly
|
|
|
|
References
|
|
----------
|
|
[1] https://www.python.org/
|
|
[2] https://www.haskell.org/
|
|
[3] https://webassembly.org/
|
|
[4] https://www.w3.org/TR/wasm-core-1/
|
|
[5] https://en.wikipedia.org/w/index.php?title=WebAssembly&oldid=1103639883
|