#+title: ARL - Issue tracker
#+date: 2026-01-23

* TODO Write a minimum working transpiler
We need to be able to compile the following file:
[[file:examples/hello-world.arl]].  All it does is print "Hello,
world!".  Should be relatively straightforward.
** DONE Read file
** DONE Parser
** TODO Intermediate representation (Virtual Machine)
[[file:src/arl/vm/]]

Before we get into generating C code and then compiling it, it might
be worth translating the parsed ARL code into a generic IR.

The IR should be much more primitive in its semantics, and force clear
requirements of the platform we're compiling to.  This way, at the
code generator stage we can figure out:
- what can we reasonably use from the target platform to satisfy
  requirements?
- what do we need to hand-roll on the target in order to make this
  work?

Essentially, we want to write a virtual machine, and translate ARL
code into bytecode for that VM.  Goals:
- Easier to optimise IR bytecode than the AST of our original program
- Easier to imagine translations from that IR bytecode into target
  platform code
*** TODO Minimal IR representation
We need the following clear items in our IR:
- Static type values
- Static type variables (possible DeBrujin numbering or other such
  mechanism to abstract naming away and leave it to the target to
  generate effectively)
- Strongly typed primitive operators (numeric, strings, I/O) with
  packed arguments

Read about [[https://en.wikipedia.org/wiki/Three-address_code][TAC]].
*** TODO IR Compiler
We should have a rough grouping between AST objects and this IR.  As
ARL is Forth-like, we can use the stack semantics to generate this IR
as we walk the AST in a linear manner.

Consider the following ARL code:
#+begin_src text
34 35 +
#+end_src

When we walk through this code:
- 34 (an integer) is pushed onto the stack
- 35 (an integer) is pushed onto the stack
- + is encountered
  - Pop two values off the stack and verify their type against the
    contract for "+" (something like (-> i32 i32 i32))
  - Generate IR, something like ~prim-add(34, 35)~
*** TODO Consider optimisers
Certainly we should perform optimisations on the IR itself before
passing it over to the code generator.  Currently we haven't got much
in the way of optimisations to consider, but it may be worth
considering.
** TODO Code generator
[[file:src/arl/target-c/]]

This should take the IR translated from the AST generated by the
parser, and write equivalent C code.

After we've generated the C code, we need to call a C compiler on it
to generate a binary.  GCC and Clang allow passing source code through
stdin, so we don't even need to write to disk first which is nice.