From 1c5f3d631def032de5e3f781e7b8b6206cf7b9ab Mon Sep 17 00:00:00 2001
From: Abin Simon <abinsimon10@gmail.com>
Date: Fri, 14 Oct 2022 04:37:59 +0530
Subject: [PATCH] Update builds docs (#1151)

## Description

Adds more info in the build docs for building corso binary locally or using containers. Also improved docs on building corso container image.

@gmatev let me know if I should add anything else specifically to the docs.

## Type of change

<!--- Please check the type of change your PR introduces: --->
- [ ] :sunflower: Feature
- [ ] :bug: Bugfix
- [x] :world_map: Documentation
- [ ] :robot: Test
- [ ] :computer: CI/Deployment
- [ ] :hamster: Trivial/Minor

## Issue(s)

<!-- Can reference multiple issues. Use one of the following "magic words" - "closes, fixes" to auto-close the Github issue. -->
* fixes #684

## Test Plan

<!-- How will this be tested prior to merging.-->
- [x] :muscle: Manual
- [ ] :zap: Unit test
- [ ] :green_heart: E2E
---
 docs/.vale.ini                |  4 ++-
 docs/docs/developers/build.md | 55 +++++++++++++++++++++++++++++++----
 2 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/docs/.vale.ini b/docs/.vale.ini
index e81774ef4..6ccb3ad7e 100644
--- a/docs/.vale.ini
+++ b/docs/.vale.ini
@@ -20,7 +20,9 @@ BasedOnStyles = Vale, Microsoft, proselint, write-good, alex
 # - corso command line examples first line in a bash code block starting with `corso`
 BlockIgnores = (\{\#.*?\}), \
                (import.*?from.*?;),\
-               (?s) (```bash.*?corso.*?$)
+               (?s) (```bash.*?corso.*?$), \
+               (?s) (```bash.*?\/build.*?$)
+
 
 [*.json]
 BasedOnStyles = Vale
diff --git a/docs/docs/developers/build.md b/docs/docs/developers/build.md
index d697b98a7..26868a2cf 100644
--- a/docs/docs/developers/build.md
+++ b/docs/docs/developers/build.md
@@ -1,20 +1,63 @@
 # Building Corso
 
+## Binary
+
+### Building locally
+
+Corso is a Go project, and you can build it with `go build` from `<repo root>/src`
+if you have Go installed on your system.
+
+```bash
+# run from within `./src`
+go build -o corso 
+```
+
+:::info
+If you dong have Go available, you can find installation instructions [here](https://go.dev/doc/install)
+:::
+
+This will generate a binary named `corso` in the directory where you run the build.
+
+### Building via Docker
+
 For convenience, the Corso build tooling is containerized. To take advantage, you need
 [Docker](https://www.docker.com/) installed on your machine.
 
-To build Corso locally, use the following command from the root of your repo:
+To build Corso via docker, use the following command from the root of your repo:
 
 ```bash
-./build/build.sh 
-
+./build/build.sh
 ```
 
-The resulting binary will be under `<repo root>/bin`
+You can pass in all the architectures/platforms you would like to
+build it for using the `--platforms` flag as a comma separated
+list. For example, if you would like to build `amd64` and `arm64`
+versions for Linux, you can run the following command:
 
-If you prefer to build Corso as a container, use the following command:
+```bash
+./build/build.sh --platforms linux/amd64,linux/arm64
+```
+
+Once built, the resulting binaries will be available in `<repo root>/bin` for all the different platforms you specified.
+
+## Container Image
+
+If you prefer to build Corso as a container image, use the following command instead:
 
 ```bash
 # Use --help to see all available options
-./build/build-container.sh 
+./build/build-container.sh
+```
+
+Below are the main customization flags that you can set when building a container image:
+
+- `-a|--arch`: Set the architecture to the specified value. (default: amd64)
+- `-l|--local`: Build the corso binary on your local system, rather than a go image.
+- `-p|--prefix`: Prefix for the image name.
+- `-s|--suffix`: Suffix for the version.
+
+For example, you can use the following command to create a `arm64` image with prefix of `ghcr.io` and the tag as `nightly`.
+
+```bash
+./build/build-container.sh --arch arm64 --prefix ghcr.io --suffix nightly
 ```