From dedb8154e5d98a0daa06de60ddf9d6fd421ff167 Mon Sep 17 00:00:00 2001
From: Bryan English <bryan@rethought.computer>
Date: Mon, 9 Feb 2026 22:43:39 -0500
Subject: [PATCH] dev docs, and some cleanup

---
 rel-lang/docs/hacking.md                      | 74 +++++++++++++++++++
 .../full-fib}/compile.sh                      |  0
 .../full-fib}/fib.rel                         |  0
 .../{fib-example => examples/full-fib}/putn.c |  0
 rel-lang/flake.nix                            |  6 --
 5 files changed, 74 insertions(+), 6 deletions(-)
 create mode 100644 rel-lang/docs/hacking.md
 rename rel-lang/{fib-example => examples/full-fib}/compile.sh (100%)
 rename rel-lang/{fib-example => examples/full-fib}/fib.rel (100%)
 rename rel-lang/{fib-example => examples/full-fib}/putn.c (100%)

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/fib-example/compile.sh b/rel-lang/examples/full-fib/compile.sh
similarity index 100%
rename from rel-lang/fib-example/compile.sh
rename to rel-lang/examples/full-fib/compile.sh
diff --git a/rel-lang/fib-example/fib.rel b/rel-lang/examples/full-fib/fib.rel
similarity index 100%
rename from rel-lang/fib-example/fib.rel
rename to rel-lang/examples/full-fib/fib.rel
diff --git a/rel-lang/fib-example/putn.c b/rel-lang/examples/full-fib/putn.c
similarity index 100%
rename from rel-lang/fib-example/putn.c
rename to rel-lang/examples/full-fib/putn.c
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 {
-- 
2.43.0