From 90d16ca3bab4ee3b7d56e29fa0d0d38b8e19843d Mon Sep 17 00:00:00 2001 From: "Lance R. Vick" 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 +```