jbwdevries/phasm
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Updates the README for clarity

Browse Source
This commit is contained in:
Johan B.W. de Vries 2025-06-07 14:00:03 +02:00
parent 8a1a6af3e7
commit 544bbfac72
1 changed files with 56 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
README.md
View File

@ -3,46 +3,14 @@ phasm
Elevator pitch
--------------
A programming language, that looks like Python, handles like Haskell,
A programming language that looks like Python, handles like Haskell,
and compiles directly to WebAssembly.
Project state
-------------
This is a hobby project for now. Use at your own risk.
How to run
----------
You should only need make and python3. Currently, we're working with python3.10,
since we're using the python ast parser, it might not work on other versions.
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
```
To compile a Phasm file:
```sh
python3.12 -m phasm source.py output.wat
```
Additional required tools
-------------------------
At the moment, the compiler outputs WebAssembly text format. To actually
get a binary, you will need the wat2wasm tool[6].
Example
-------
For more examples, see the examples directory.
From `examples/fib.py`:
```py
def helper(n: u64, a: u64, b: u64) -> u64:
if n < 1:
@ -61,6 +29,55 @@ def fib(n: u64) -> u64:
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
@ -83,6 +100,9 @@ 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
@ -96,10 +116,3 @@ References
[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
[6] https://github.com/WebAssembly/wabt
Links
-----
- https://pengowray.github.io/wasm-ops/
Shorthand overview for supported operations in WebAssembly.