From b905e61ae0dae0dec58fa9657d4e1514566b143f Mon Sep 17 00:00:00 2001
From: Mitchell Riedstra <mitch@riedstra.dev>
Date: Mon, 12 Jan 2026 20:22:17 -0500
Subject: Reduce the size of the Linux system. Add a better readme.

---
 readme.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 2 deletions(-)

(limited to 'readme.md')

diff --git a/readme.md b/readme.md
index c7c44c6..883574b 100644
--- a/readme.md
+++ b/readme.md
@@ -5,5 +5,60 @@ Which itself is dumped from: https://archive.org/details/utah_unix_v4_raw
 
 Also includes jslinux for running the image from a browser.
 
-This a hacky and messy repo put together in just a few hours to let people
-play around with Unix v4 in their web browser.
+This a bit hacky repo put together a few hours to let people play around with
+Unix v4 in their web browser.
+
+## Building it yourself:
+
+podman or docker on Linux x86 or amd64 is ideal.
+
+```
+$ sh ./build.sh
+```
+
+This will:
+
+  * Pull down simh from github
+  * create an alpine linux container, build simh, and strip down the deps
+  * export the container to a tarball
+  * create a disk image and setup a filesystem on a loopback device ( requires
+    `kpartx` )
+
+From there to load the disk image into the jslinux emulator you will need
+the `splitimg` utility, a binary is checked in if you're on a recent Linux
+machine, or compile it from the incuded sources:
+
+```
+$ cd jslinux-2019-12-21/
+$ cp ../disk.img ./
+$ ./splitimg root-x86.bin root-x86 4096
+```
+
+The `jslinux-2019-12-21` directory can then be copied to any plain HTTP server.
+
+## Running UnixV4 locally
+
+The `build.sh` script dumps out a statically linked `pdp11` simulator from
+the tarball, it should work on most x86 Linux machines, if you don't wish
+to build the image simply run the build script with the `-bin-only` flag,
+i.e.
+
+```
+$ ./build.sh -bin-only
+```
+
+From there you can run the `pdp11` binary from the local directory:
+
+```
+$ ./pdp11 boot.ini
+```
+
+
+### Building simh on other architectures
+
+Removing the `--platform` flag from the `build.sh` and `-march=i386`
+from the `Containerfile` should suffice assuming there's an upstream
+Alpine Linux container for your architecture.
+
+Note, this will not work with JSLinux. Though, you could in theory
+build for riscv and tweak the html to load that emulator instead.
-- 
cgit v1.2.3