s2n-tls build section

docs/BUILD.md

@@ -1,4 +1,4 @@
-# Building s2n-tls
+# s2n-tls Build Instructions
 
 ## Obtaining s2n-tls
 
@@ -7,19 +7,9 @@ s2n-tls can be obtained by cloning the s2n-tls Github repo locally:
 git clone https://github.com/aws/s2n-tls.git
 ```
 
-## Obtaining a libcrypto
+## Building s2n-tls
 
-s2n-tls has a single code dependency on a libcrypto library. The libcrypto contains all the cryptographic operations used to negotiate TLS and encrypt/decrypt data. s2n-tls must be linked to a libcrypto library when building. The following libcrypto libraries are currently supported:
-- [AWS-LC](https://github.com/aws/aws-lc)
-- [OpenSSL](https://github.com/openssl/openssl) (versions 1.0.2 - 3.0)
-- [BoringSSL](https://boringssl.googlesource.com/boringssl)
-- [LibreSSL](https://www.libressl.org/)
-
-Any of the above libcryptos can be built from source and linked with s2n-tls. Please refer to the desired project's build instructions for help building the libcrypto on your operating system.
-
-### AWS-LC
-
-[AWS-LC](https://github.com/aws/aws-lc) is the recommended libcrypto to use with s2n-tls due to increased performance and security guarantees. AWS-LC can be built via the following:
+The following commands can be used to build s2n-tls with minimal configuration options:
 
 <details open>
 <summary>Ubuntu</summary>
@@ -35,15 +25,17 @@ Any of the above libcryptos can be built from source and linked with s2n-tls. Pl
 # install build dependencies
 brew install cmake ninja go
 
-# clone aws-lc locally
-git clone https://github.com/aws/aws-lc.git
-cd aws-lc
+# MacOS does not have a supported libcrypto preinstalled, but OpenSSL can be installed with brew
+brew install openssl@3
 
-# build and install aws-lc
-cmake -GNinja -B build -DCMAKE_INSTALL_PREFIX=./aws-lc-install
+# get the libcrypto install directory
+openssl_dir=$(dirname $(dirname $(brew list openssl@3|grep libcrypto.dylib)))
+
+# build s2n-tls
+cmake . -Bbuild -GNinja \
+    -DCMAKE_PREFIX_PATH=$openssl_dir
 ninja -C build
-ninja -C build run_tests
-ninja -C build install
+ninja -C build test
 ```
 </details>
 
@@ -54,31 +46,52 @@ ninja -C build install
 ```
 </details>
 
-For more information on building AWS-LC, see the [Building AWS-LC documentation](https://github.com/aws/aws-lc/blob/main/BUILDING.md)
+s2n-tls can be configured with the following cmake options. Each option can be configured by passing a `-D<option>=<value>` flag to cmake.
+- [**`CMAKE_INSTALL_PREFIX`**](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html): Specifies where the s2n-tls library and binary artifacts are placed when installing s2n-tls via `ninja -C build install`.
+- [**`CMAKE_PREFIX_PATH`**](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html): Specifies install locations used by cmake to search for library dependencies. This option can be used to link s2n-tls to a specific libcrypto. See the [Using a specific libcrypto](#using-a-specific-libcrypto) section for more information on building with different libcryptos.
+- [**`CMAKE_BUILD_TYPE`**](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html): Sets the build type. Some of the possible build types are as follows:
+  - `Release`: Produce an optimized s2n-tls library artifact with no debug info. This option should be used when building s2n-tls for use in production.
+  - `Debug`: Produce an unoptimized library artifact with debug info. This option can be used when developing for or with s2n-tls. The debug symbols produced with this build can be used with GDB or to generate more informative stack traces.
+
+The entire list of s2n-tls cmake options can be viewed with `cmake . -LH`. 
+
+## Building with a specific libcrypto
+
+s2n-tls has a single library dependency: the libcrypto. The libcrypto contains cryptographic operations used to negotiate TLS and encrypt/decrypt data. s2n-tls must be linked to a libcrypto library when building. The following libcrypto libraries are currently supported:
+- [AWS-LC](https://github.com/aws/aws-lc)
+- [OpenSSL](https://github.com/openssl/openssl) (versions 1.0.2 - 3.0)
+- [BoringSSL](https://boringssl.googlesource.com/boringssl)
+- [LibreSSL](https://www.libressl.org/)
+
+Any of the above libcryptos can be built and linked to s2n-tls by specifying the libcryot's install path with the `CMAKE_PREFIX_PATH` option. Please refer to the desired project's build instructions for help building the libcrypto on your operating system.
 
-### System libcrypto
+### AWS-LC
 
-Alternatively, operating systems typically have a supported libcrypto already installed, or provide a supported libcrypto via the system's package manager. To use a system libcrypto to build s2n-tls, the install path must be determined for your operating system. Some common install locations are as follows:
+[AWS-LC](https://github.com/aws/aws-lc) is the recommended libcrypto to use with s2n-tls due to increased performance and security. AWS-LC can be built via the following:
 
 <details open>
 <summary>Ubuntu</summary>
 
 ```
 ```
-
 </details>
 
 <details>
 <summary>MacOS</summary>
 
-MacOS does not have a supported libcrypto preinstalled. However, OpenSSL is available via the [homebrew](https://brew.sh/) package manager:
-```
-brew install openssl@3
 ```
+# install build dependencies
+brew install cmake ninja go
 
-The install path can be found with the following command:
-```
-dirname $(dirname $(brew list openssl@3|grep libcrypto.dylib))
+# clone aws-lc locally
+git clone https://github.com/aws/aws-lc.git
+cd aws-lc
+
+# build and install aws-lc
+cmake -GNinja -B build -DCMAKE_INSTALL_PREFIX=./aws-lc-install
+ninja -C build
+ninja -C build run_tests
+ninja -C build install
 ```
 </details>
 
@@ -87,8 +100,6 @@ dirname $(dirname $(brew list openssl@3|grep libcrypto.dylib))
 
 ```
 ```
-
 </details>
 
-
-
+For more information on building AWS-LC, see the [Building AWS-LC documentation](https://github.com/aws/aws-lc/blob/main/BUILDING.md)