Bootstrapping a Forth interpreter from hand-written tiny ELF binary. Just for fun.
Forth
374
560 commits
updated Aug 18, 2022
README
PlanckForth: Bootstrapping an Interpreter from Handwritten 1KB Binary
This project aims to bootstrap a Forth interpreter from hand-written tiny (1KB) ELF binary. This is just for fun. No practical use.
How to build
Only xxd is needed to build PlanckForth.
$ git clone https://github.com/nineties/planckforth.git
$ cd planckforth
$ make
xxd -r -c 8 planck.xxd > planck
chmod +x planck
Implementations in other languages are in others.
Hello World
The hello world program at the beginning looks like this.
$ ./planck
kHtketkltkltkotk tkWtkotkrtkltkdtk!tk:k0-tk0k0-Q
After bootstrapping by bootstrap.fs, it looks like this.
$ ./planck < bootstrap.fs
." Hello World!" cr
bootstrap.fs can also take a file as an input program like this.
$ cat example/fib.fs
: fib dup 2 < unless 1- dup recurse swap 1- recurse + then ;
20 fib . cr
$ ./planck < bootstrap.fs example/fib.fs
6765
Running Tests
$ make test
Builtin Words
| code | name | stack effect | semantics |
|---|---|---|---|
| Q | quit | ( n -- ) | Exit the process |
| C | cell | ( -- n ) | The size of Cells |
| h | &here | ( -- a-addr ) | The address of 'here' cell |
| l | &latest | ( -- a-addr ) | The address of 'latest' cell |
| k | key | ( -- c ) | Read character |
| t | type | ( c -- ) | Print character |
| j | jump | ( -- ) | Unconditional branch |
| J | 0jump | ( n -- ) | Jump if a == 0 |
| f | find | ( c -- xt ) | Get execution token of c |
| x | execute | ( xt -- ... ) | Run the execution token |
| @ | fetch | ( a-addr -- w ) | Load value from addr |
| ! | store | ( w a-addr -- ) | Store value to addr |
| ? | cfetch | ( c-addr -- c ) | Load byte from addr with sign extension |
| $ | cstore | ( c c-addr -- ) | Store byte to addr |
| d | dfetch | ( -- a-addr ) | Get data stack pointer |
| D | dstore | ( a-addr -- ) | Set data stack pointer |
| r | rfetch | ( -- a-addr ) | Get return stack pointer |
| R | rstore | ( a-addr -- ) | Set return stack pointer |
| i | docol | ( -- a-addr ) | Get the code pointer of interpreter |
| e | exit | ( -- ) | Exit current function |
| L | lit | ( -- n ) | Load immediate |
| S | litstring | ( -- c-addr ) | Load string literal |
| + | add | ( a b -- c ) | c = (a + b) |
| - | sub | ( a b -- c ) | c = (a - b) |
| * | mul | ( a b -- c ) | c = (a * b) |
| / | divmod | ( a b -- c d ) | c = (a mod b), d = (a / b) |
| & | and | ( a b -- c ) | c = (a & b) |
| | | or | ( a b -- c ) | c = (a | b) |
| ^ | xor | ( a b -- c ) | c = (a ^ b) |
| < | less | ( a b -- c ) | c = (a < b) |
| u | uless | ( a b -- c ) | c = (a unsigned< b) |
| = | equal | ( a b -- c ) | c = (a == b) |
| ( | shl | ( a b -- c ) | c = a << b (logical) |
| ) | shr | ( a b -- c ) | c = a >> b (logical) |
| % | sar | ( a b -- c ) | c = a >> b (arithmetic) |
| v | argv | ( -- a-addr u ) | argv and argc |
| V | version | ( -- c-addr ) | Runtime infomation string |
Binary Layout
Implementations
| Implementation of runtime | build | test status |
|---|---|---|
| Handwritten ELF binary for i386-linux | make |  |
| C | make c |  |
| Python 3.x | make python |  |
Benchmarks
See Wiki/Benchmarks
Contributors
Similar repos
Languages
Forth
91.2%
Python
4.1%
C
3.4%
Bootstrapping a Forth interpreter from hand-written tiny ELF binary. Just for fun.
Forth
374
560 commits
updated Aug 18, 2022
README
PlanckForth: Bootstrapping an Interpreter from Handwritten 1KB Binary
This project aims to bootstrap a Forth interpreter from hand-written tiny (1KB) ELF binary. This is just for fun. No practical use.
How to build
Only xxd is needed to build PlanckForth.
$ git clone https://github.com/nineties/planckforth.git
$ cd planckforth
$ make
xxd -r -c 8 planck.xxd > planck
chmod +x planck
Implementations in other languages are in others.
Hello World
The hello world program at the beginning looks like this.
$ ./planck
kHtketkltkltkotk tkWtkotkrtkltkdtk!tk:k0-tk0k0-Q
After bootstrapping by bootstrap.fs, it looks like this.
$ ./planck < bootstrap.fs
." Hello World!" cr
bootstrap.fs can also take a file as an input program like this.
$ cat example/fib.fs
: fib dup 2 < unless 1- dup recurse swap 1- recurse + then ;
20 fib . cr
$ ./planck < bootstrap.fs example/fib.fs
6765
Running Tests
$ make test
Builtin Words
| code | name | stack effect | semantics |
|---|---|---|---|
| Q | quit | ( n -- ) | Exit the process |
| C | cell | ( -- n ) | The size of Cells |
| h | &here | ( -- a-addr ) | The address of 'here' cell |
| l | &latest | ( -- a-addr ) | The address of 'latest' cell |
| k | key | ( -- c ) | Read character |
| t | type | ( c -- ) | Print character |
| j | jump | ( -- ) | Unconditional branch |
| J | 0jump | ( n -- ) | Jump if a == 0 |
| f | find | ( c -- xt ) | Get execution token of c |
| x | execute | ( xt -- ... ) | Run the execution token |
| @ | fetch | ( a-addr -- w ) | Load value from addr |
| ! | store | ( w a-addr -- ) | Store value to addr |
| ? | cfetch | ( c-addr -- c ) | Load byte from addr with sign extension |
| $ | cstore | ( c c-addr -- ) | Store byte to addr |
| d | dfetch | ( -- a-addr ) | Get data stack pointer |
| D | dstore | ( a-addr -- ) | Set data stack pointer |
| r | rfetch | ( -- a-addr ) | Get return stack pointer |
| R | rstore | ( a-addr -- ) | Set return stack pointer |
| i | docol | ( -- a-addr ) | Get the code pointer of interpreter |
| e | exit | ( -- ) | Exit current function |
| L | lit | ( -- n ) | Load immediate |
| S | litstring | ( -- c-addr ) | Load string literal |
| + | add | ( a b -- c ) | c = (a + b) |
| - | sub | ( a b -- c ) | c = (a - b) |
| * | mul | ( a b -- c ) | c = (a * b) |
| / | divmod | ( a b -- c d ) | c = (a mod b), d = (a / b) |
| & | and | ( a b -- c ) | c = (a & b) |
| | | or | ( a b -- c ) | c = (a | b) |
| ^ | xor | ( a b -- c ) | c = (a ^ b) |
| < | less | ( a b -- c ) | c = (a < b) |
| u | uless | ( a b -- c ) | c = (a unsigned< b) |
| = | equal | ( a b -- c ) | c = (a == b) |
| ( | shl | ( a b -- c ) | c = a << b (logical) |
| ) | shr | ( a b -- c ) | c = a >> b (logical) |
| % | sar | ( a b -- c ) | c = a >> b (arithmetic) |
| v | argv | ( -- a-addr u ) | argv and argc |
| V | version | ( -- c-addr ) | Runtime infomation string |
Binary Layout
Implementations
| Implementation of runtime | build | test status |
|---|---|---|
| Handwritten ELF binary for i386-linux | make | |
| C | make c | |
| Python 3.x | make python | |
Benchmarks
See Wiki/Benchmarks
Similar repos
Contributors
Languages
Forth
91.2%
Python
4.1%
C
3.4%