From 90d16ca3bab4ee3b7d56e29fa0d0d38b8e19843d Mon Sep 17 00:00:00 2001
From: "Lance R. Vick" <lance@lrvick.net>
Date: Fri, 27 Jan 2023 16:52:14 -0800
Subject: [PATCH] more useful setup instructions

---
 README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 69 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 2b501be..72d9120 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,8 @@
 ## About ##
 
 A library of opinionated make functions targeting projects that either need
-deterministic builds, or a shared deterministic toolchain shared across all
-who use a project.
+deterministic builds, or a deterministic toolchain shared across all who use a
+project.
 
 A dev of a Toolchain enabled project should never need to have anything
 on their host system installed but docker, and git. Everything else will be
@@ -38,22 +38,79 @@ us as desired.
 * docker 18+
 * GNU Make 4+
 
-## Build ##
+## Setup ##
+
+1. Clone toolchain as a git submodule somewhere in your project
+
+    ```
+    git submodule add https://codeburg.org/distrust/toolchain src/toolchain
+    ```
+
+2. Include toolchain Makefile in your root Makefile
+
+    ```
+    include src/toolchain/Makefile
+    ```
+
+3. Define any build/dev dependencies for toolchain container
+
+    ```
+    echo "libfaketime" >> config/toolchain/packages-base.txt
+    echo "build-essential" >> config/toolchain/packages-base.txt
+    ```
+
+4. Lock a base Debian container image hash
+
+    ```
+    echo "DEBIAN_HASH=48b28b354484a7f0e683e340fa0e6e4c4bce3dc3aa0146fc2f78f443fde2c55d" >> config/global.env
+    ```
+
+5. Generate hashlocks files for all toolchain container dependencies
+    ```
+    make toolchain-update
+    ```
+
+6. Define your artifact targets
+
+    ```
+    $(OUT_DIR)/hello: toolchain \
+    	$(call toolchain,$(USER)," \
+        cd $(SRC_DIR)/; \
+        gcc hello.c -o $(OUT_DIR)/hello
+    	")
+    ```
+
+7. Define a release target for your project depending on manifest.txt
+
+    ```
+    .PHONY: release
+    release: $(OUT_DIR)/hello $(OUT_DIR)/manifest.txt
+    	mkdir -p $(RELEASE_DIR)
+    	cp $(OUT_DIR)/my-binary $(RELEASE_DIR)/hello
+    	cp $(OUT_DIR)/release.env $(RELEASE_DIR)/release.env
+    	cp $(OUT_DIR)/manifest.txt $(RELEASE_DIR)/manifest.txt
+    ```
+
+    Note that manifest.txt is optional, but it makes for an ideal single file
+    to sign if a release will contain more than one artifact.
+
+
+## Usage ##
 
 ### Build a new release
 
-    ```
-    make VERSION=1.0.0rc1 release
-    ```
+```
+make VERSION=1.0.0rc1 release
+```
 
 ### Reproduce an existing release
 
-    ```
-    make VERSION=1.0.0rc1 attest
-    ```
+```
+make VERSION=1.0.0rc1 attest
+```
 
 ### Sign an existing release
 
-    ```
-    make VERSION=1.0.0rc1 sign
-    ```
+```
+make VERSION=1.0.0rc1 sign
+```