From: Bryan English <bryan@rethought.computer>
Date: Tue, 10 Feb 2026 03:43:39 +0000 (-0500)
Subject: dev docs, and some cleanup
X-Git-Url: https://rethought.computer/gitweb//gitweb//git?a=commitdiff_plain;h=dedb8154e5d98a0daa06de60ddf9d6fd421ff167;p=sorel-lang.git

dev docs, and some cleanup
---

diff --git a/rel-lang/docs/hacking.md b/rel-lang/docs/hacking.md
new file mode 100644
index 0000000..fe7323d
--- /dev/null
+++ b/rel-lang/docs/hacking.md
@@ -0,0 +1,74 @@
+## Developer setup
+
+### Nix / NixOS
+
+If you're using `Nix` or `NixOS`, the provided `flake.nix` should give you a good start.
+You'll need a recent Rust toolchain, for which you can use [`rustup`](https://rustup.sh).
+Currently that's assumed to be included on the system.
+Also, the test scripts currently assume binfmt is set up for RISC-V 64 (or that you're running on RISC-V 64).
+Assuming you're not on RISC-V 64 (most people aren't), you can add the following to your Nix `configuration.nix`:
+
+```
+
+  boot.binfmt.emulatedSystems = [
+    "riscv64-linux"
+    # ....
+  ];
+```
+
+### Ubuntu
+
+```
+# On non RISC-V 64 systems:
+apt install -y build-essential gdb crossbuild-essential-riscv64 qemu-system qemu-user qemu-user-binfmt
+```
+
+## Building the Compiler
+
+The compiler is written in Rust, and can be compiled with 
+
+```
+cargo build
+```
+
+This puts the compiler binary at `target/debug/sorelc`.
+Release builds can also be created in the usual Rust/`cargo` fasion.
+
+Note that if you change any stdlib files, you'll need to rebuild.
+
+## Compiling a Sorel Program
+
+Currently, `sorelc` takes only one argument, and that's an entrypoint for your program.
+Any words in that file outside word definitions will constitute the "main" of your program.
+
+This will create a file of the same name alongside it, with the extension changed to `asm`.
+This is a RISC-V 64 assembly file, suitable for use with GNU Assembler.
+You can assemble this as normal, and run your program.
+
+## Testing
+
+The `tests` directory contains a shell script you can invoke with `sh test.sh`.
+It should run just fine given the above setup, provided you've done a `cargo build` to build the compiler.
+This will compile the test binary using `sorelc` and your local `riscv64` assembler.
+It will run the binary using binfmt, which instructs the kernel to run your binary using `qemu-user`.
+
+### Debugging
+
+You can use `gdb`!
+Unfortunately, with `qemu-user` we can't just load the binary directly into `gdb`.
+Instead, we'll need to run `qemu-user` on a RISC-V 64 binary with a debugger port open:
+
+```
+qemu-riscv64 -g 4567 ./test1.out
+```
+
+Then, you can fire up `gdb`, and once inside it's prompt, connect to the "remote" port.
+
+```
+target remote :4567
+```
+
+Then you can use normal gdb commands!
+The `tui layout asm` is highly recommended.
+Note that if you'l linking `putstack.c`, that will use libc, which drastically inflates the binary and hijack's init.
+This can make things quite a pain in `gdb`, so try to build without it (i.e. uncomment the LD line and comment out the CC line in `test.sh`, and remove all references to `putstack` in code).
diff --git a/rel-lang/examples/full-fib/compile.sh b/rel-lang/examples/full-fib/compile.sh
new file mode 100644
index 0000000..6ef003e
--- /dev/null
+++ b/rel-lang/examples/full-fib/compile.sh
@@ -0,0 +1,4 @@
+../target/debug/sorelc fib.sorel
+riscv64-unknown-linux-gnu-as -o fib.o fib.asm
+riscv64-unknown-linux-gnu-cc -O1 -no-pie -o test.out fib.o putn.c -nostartfiles 
+./test.out
diff --git a/rel-lang/examples/full-fib/fib.rel b/rel-lang/examples/full-fib/fib.rel
new file mode 100644
index 0000000..2407f15
--- /dev/null
+++ b/rel-lang/examples/full-fib/fib.rel
@@ -0,0 +1,24 @@
+\ foo bar
+: fib
+    dup
+    1
+    >
+    if
+        dup
+        1 - fib
+        swap
+        2
+        -
+        fib
+        +
+    endif
+;
+
+0 fib putn drop
+1 fib putn drop
+2 fib putn drop
+3 fib putn drop
+4 fib putn drop
+5 fib putn drop
+6 fib putn drop
+7 fib putn drop
diff --git a/rel-lang/examples/full-fib/putn.c b/rel-lang/examples/full-fib/putn.c
new file mode 100644
index 0000000..201050c
--- /dev/null
+++ b/rel-lang/examples/full-fib/putn.c
@@ -0,0 +1,16 @@
+#include <stdio.h>
+
+extern unsigned long data_stack_end;
+register unsigned long * stack_pointer asm("s2");
+
+void putn() {
+  unsigned long * stack_index = &data_stack_end;
+  printf("stack: ");
+  while (stack_index != stack_pointer) {
+	  printf("%ld ", *stack_index);
+    stack_index -= 1;
+  }
+	printf("%ld\n", *stack_pointer);
+}
+
+
diff --git a/rel-lang/fib-example/compile.sh b/rel-lang/fib-example/compile.sh
deleted file mode 100644
index 6ef003e..0000000
--- a/rel-lang/fib-example/compile.sh
+++ /dev/null
@@ -1,4 +0,0 @@
-../target/debug/sorelc fib.sorel
-riscv64-unknown-linux-gnu-as -o fib.o fib.asm
-riscv64-unknown-linux-gnu-cc -O1 -no-pie -o test.out fib.o putn.c -nostartfiles 
-./test.out
diff --git a/rel-lang/fib-example/fib.rel b/rel-lang/fib-example/fib.rel
deleted file mode 100644
index 2407f15..0000000
--- a/rel-lang/fib-example/fib.rel
+++ /dev/null
@@ -1,24 +0,0 @@
-\ foo bar
-: fib
-    dup
-    1
-    >
-    if
-        dup
-        1 - fib
-        swap
-        2
-        -
-        fib
-        +
-    endif
-;
-
-0 fib putn drop
-1 fib putn drop
-2 fib putn drop
-3 fib putn drop
-4 fib putn drop
-5 fib putn drop
-6 fib putn drop
-7 fib putn drop
diff --git a/rel-lang/fib-example/putn.c b/rel-lang/fib-example/putn.c
deleted file mode 100644
index 201050c..0000000
--- a/rel-lang/fib-example/putn.c
+++ /dev/null
@@ -1,16 +0,0 @@
-#include <stdio.h>
-
-extern unsigned long data_stack_end;
-register unsigned long * stack_pointer asm("s2");
-
-void putn() {
-  unsigned long * stack_index = &data_stack_end;
-  printf("stack: ");
-  while (stack_index != stack_pointer) {
-	  printf("%ld ", *stack_index);
-    stack_index -= 1;
-  }
-	printf("%ld\n", *stack_pointer);
-}
-
-
diff --git a/rel-lang/flake.nix b/rel-lang/flake.nix
index 0e88f67..8aacadf 100644
--- a/rel-lang/flake.nix
+++ b/rel-lang/flake.nix
@@ -8,12 +8,6 @@
   outputs = {nixpkgs, ...}: let
     system = "x86_64-linux";
     pkgs = import nixpkgs {
-      # uncomment the next bit to install cross-compiler toolchain
-      # crossSystem = {
-      #   config = "riscv64-unknown-linux-gnu";
-      #   # Or if you want to build against MUSL:
-      #   # config = "riscv64-unknown-linux-musl";
-      # };
       inherit system;
     };
   in {