From c5f436b4d06b18af53c69a9ed8aba5430a75219b Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jandd@cacert.org>
Date: Tue, 29 Nov 2022 20:12:04 +0100
Subject: [PATCH] Add development documentation

---
 README.md | 41 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f15cbb1..e8e7291 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,37 @@
-# Running with softhsm2
+# CAcert signer
 
-## Setup HSM keys and certificates
+This is the CAcert signer reimplementation in Go that implements a more robust wire protocol and has configurable
+support for hardware security modules (HSMs) for online and offline key pairs.
+
+See [the design document](docs/design.md) for design considerations and architecture diagrams.
+
+## Development preconditions
+
+You will need GNU make to build the application. On Debian systems you can install GNU make and crossbuild tools
+for ARM binary builds using:
+
+```shell
+sudo apt install make crossbuild-essential-arm64 crossbuild-essential-armhf
+```
+
+Install [go](https://go.dev/) >= 1.17, [golangci-lint](https://golangci-lint.run/usage/install/) >= 1.50.0 and
+[goreleaser](https://goreleaser.com/install/), as these are used for building and linting the application.
+
+Read the documentation of these tools, to find out how to use them.
+
+## Building the binaries
+
+There is a `Makefile` to automate builds of the signer and clientsim binaries. Run
+
+```shell
+make
+```
+
+to run linting, tests and binary builds.
+
+## Running with softhsm2
+
+### Setup HSM keys and certificates
 
 ```shell
 sudo apt install softhsm2
@@ -15,14 +46,14 @@ export PKCS11_PIN_LOCALHSM=123456
 go run ./cmd/signer -setup
 ```
 
-## Run the signer
+### Run the signer
 
 ```shell
 export PKCS11_PIN_LOCALHSM=123456
 go run ./cmd/signer
 ```
 
-## Run the client simulator with socat
+### Run the client simulator with socat
 
 You may run the client simulator that sends commands via `stdout` and reads responses on `stdin` via `socat` to
 simulate traffic on an emulated serial device:
@@ -32,7 +63,7 @@ sudo apt install socat
 ```
 
 ```shell
-go build ./cmd/clientsim
+make clientsim
 socat -d -d -v pty,rawer,link=$(pwd)/testPty EXEC:./clientsim,pty,rawer
 ```