README and arl.org

arl.org

@@ -0,0 +1,69 @@
+#+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.