From 639ceb3c933a8d03798e91cbfb10a0f95ebfe641 Mon Sep 17 00:00:00 2001
From: Aryadev Chavali <aryadev@aryadevchavali.com>
Date: Sat, 24 Jan 2026 00:35:38 +0000
Subject: [PATCH] README and arl.org

---
 README  | 46 ++++++++++++++++++++++++++++++++++++++
 arl.org | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+)
 create mode 100644 arl.org

diff --git a/README b/README
index e69de29..4f38bf1 100644
--- a/README
+++ b/README
@@ -0,0 +1,46 @@
+┌───────────────────────┐
+│     _    ____  _      │
+│    / \  |  _ \| |     │
+│   / _ \ | |_) | |     │
+│  / ___ \|  _ <| |___  │
+│ /_/   \_\_| \_\_____| │
+└───────────────────────┘
+
+Similar to Forth.  Compiles to C.
+Native speed with simple semantics.
+
+-----
+Goals
+-----
+- Complete operational transpiler to C
+- Ability to reuse compiled code (as object code) in top level ARL code.
+- Static type system with informative errors
+
+-------------
+Issue tracker
+-------------
+See arl.org.
+
+------------
+Requirements
+------------
+- C compiler with support for C23, accessible via PATH
+- GNU Make
+
+------------------
+Build instructions
+------------------
+$ make
+... will generate a binary "arlc.out" in the build folder, which may be used to
+compile ".arl" files into native code.
+
+$ make MODE=debug
+... will generate a debug binary that may be used for further examination and
+logging.
+
+You may specify the folder build artifacts are generated in by setting the DIST
+variable in your make invocation i.e.
+$ make DIST=<folder>
+
+Similarly, the general flags used in the C compiler may be set via the CFLAGS
+variable, with linking arguments set via the LDFLAGS variable.
diff --git a/arl.org b/arl.org
new file mode 100644
index 0000000..c8c9cfd
--- /dev/null
+++ b/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.