From 08b5d7539cb1f21f4906dd496a317616a014aec9 Mon Sep 17 00:00:00 2001
From: kayomn <kayomn@kayomn.net>
Date: Wed, 24 Jul 2024 00:54:14 +0100
Subject: [PATCH] Update readme with promotional content and new build
 instructions

---
 .gitattributes    |  1 +
 promo/effects.png |  3 ++
 readme.md         | 71 +++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 72 insertions(+), 3 deletions(-)
 create mode 100644 promo/effects.png

diff --git a/.gitattributes b/.gitattributes
index 3a63264..f94efde 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1,3 @@
 *.bmp filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
 *.spv filter=lfs diff=lfs merge=lfs -text
diff --git a/promo/effects.png b/promo/effects.png
new file mode 100644
index 0000000..2398238
--- /dev/null
+++ b/promo/effects.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f2ebfe7d09a3201ef4e93d194cc5633e33958972c50da8da78fe2e8e2a741937
+size 90468
diff --git a/readme.md b/readme.md
index bf956f6..4b93ccf 100644
--- a/readme.md
+++ b/readme.md
@@ -1,5 +1,7 @@
 # Ona
 
+![Screenshot of Ona rendering a CRT display distrotion effect on the default texture](promo/effects.png)
+
 ## Table of Contents
 
 1. [Overview](#overview)
@@ -32,12 +34,75 @@ Ona is also the Catalan word for "wave".
 
 Ona currently depends the following third-party tools to build it:
 
-  * Platform support for SDL2 at version 2.0.20 or above.
-  * SPIR-V shader compilation system utilities, namely `glslangValidator`.
+  * Platform support for SDL2 at version 2.0.20 installed via the standard shared binary format redistributable.
+  * SPIR-V shader compilation system utilities available from the system path, namely `glslangValidator`.
   * Zig compiler toolchain.
 
 As the project evolves, dependencies on libraries external to the project codebase will be minimized or removed outright to meet the goals of the project as closely as possible.
 
 ### Building
 
-Once all third-party tools and system-wide dependencies are satisfied, navigate to the root project folder and run `zig build` to build everything.
+After the repository has finished cloning, you will then want to also clone all Git submodule dependencies via the `git submodule update --init --recursive` command. If you are using a Git front-end, this may be a menu option or is handled *automagically*, it varies depending on the front-end.
+
+Once all third-party tools and dependencies are satisfied, navigate to the root project folder and run `zig build demos` to build the demo executables. The resulting binaries will be placed in `/demos` will a name respective to the source file it was built from.
+
+To experiment without creating your own Zig project, you can create a new uniquely named source file in this directory and the `zig build demos` step will (re)build it along with everything else.
+
+The unit testing suite for the engine modules (`src/ona`, `src/coral`, etc.) may be built and ran via `zig build tests`.
+
+Tests are ran by our continuous integration host so should these shouldn't fail locally without user intervention. If they do, feel free to report an issue via my email linked in my Sauce Control bio or through any other means of public communication I have.
+
+### Packaging
+
+Since this is a Zig package it can be consumed via the Zig package manager using the usual steps.
+
+(These steps have been adapted from [Andre Weissflog's tutorial for for setting up Sokol with Zig package manager](https://github.com/floooh/sokol-zig/blob/master/README.md).)
+
+  1. Create a new Zig project if you have not already.
+  2. Create a `build.zig.zon` accompanying your `build.zig` if you do not already have one.
+  3. Your `build.zig.zon` should, at minimum, contain the following dependency listed in the dependencies section:
+
+```zig
+.{
+    .dependencies = .{
+        .ona = .{
+            .url = "git+https://sauce.pizzawednes.day/kayomn/ona.git#[commit-hash]",
+        },
+    },
+}
+```
+
+  4. Make sure the `[commit-hash]` is a recent commit that will work with your version of the Zig compiler and, when in doubt, choose the latest `master` commit.
+
+  5. Run `zig build` and add the content hash it outputs in your terminal to your dependencies:
+
+```zig
+.{
+    .dependencies = .{
+        .ona = .{
+            .url = "git+https://sauce.pizzawednes.day/kayomn/ona.git#[commit-hash]",
+            .hash = "[content-hash]",
+        },
+    },
+}
+```
+
+  6. Add a package declaration for Ona to your `build.zig` and add the relevant modules to your application.
+
+```zig
+const ona_dependency = b.dependency("ona", .{
+  .target = target,
+  .optimize = optimize,
+});
+
+const app = b.addExecutable(.{
+    .name = "My Ona App",
+    .target = target,
+    .optimize = optimize,
+    .root_source_file = b.path("src/main.zig"),
+});
+
+app.root_module.addImport("ona", ona_dependency.module("ona"));
+app.root_module.addImport("coral", ona_dependency.module("coral"));
+app.root_module.addImport("input", ona_dependency.module("input"));
+```