From 7d1d9b93ee904c2e3099a6a9004dc9186b642f13 Mon Sep 17 00:00:00 2001
From: Jakub Sobon <mumak@google.com>
Date: Fri, 22 Apr 2022 13:50:33 -0400
Subject: [PATCH] Updating instructions on how to build Nighthawk. (#838)

Addresses concerns raised in #832 and #833.

Signed-off-by: Jakub Sobon <mumak@google.com>
---
 README.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 92 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index e5386d307..f42e6c6da 100644
--- a/README.md
+++ b/README.md
@@ -16,30 +16,110 @@ Nighthawk currently offers:
 See [navigating the codebase](docs/root/navigating_the_codebase.md) for a
 description of the directory structure.
 
-## Prerequisites
+## Building Nighthawk
 
-### Ubuntu
+### Prerequisites
 
-First, follow steps 1 and 2 over at [Quick start Bazel build for developers](https://github.com/envoyproxy/envoy/blob/main/bazel/README.md#quick-start-bazel-build-for-developers).
+Note that Nighthawk uses [Envoy's code](https://github.com/envoyproxy/envoy)
+directly, so building Envoy is a prerequisite for building Nighthawk. Start by
+looking at [Envoy's
+building](https://www.envoyproxy.io/docs/envoy/latest/start/building.html)
+documentation.
 
+#### Compiler requirements
 
-## Building and using the Nighthawk client CLI
+The main supported way of building Nighthawk is with the Clang compiler. At
+least Clang/LLVM 12+ is needed to successfully build Nighthawk.
 
-For building the Nighthawk test server, see [here](source/server/README.md).
+#### Bazel
 
-### Test it
+Both Envoy and Nighthawk use the [Bazel](https://bazel.build/) build tool. The
+steps required to set up Bazel are documented in Envoy's [Quick start Bazel
+build for
+developers](https://github.com/envoyproxy/envoy/blob/main/bazel/README.md#quick-start-bazel-build-for-developers).
 
-```bash
-bazel test -c dbg //test/...
+### Building on Ubuntu
+
+This section outlines the steps needed to build on Ubuntu. Note that these steps
+include commands that are documented in the prerequisites section above.
+
+#### Install required packages
+
+Run the following command to install the required packages.
+```
+sudo apt-get install \
+   autoconf \
+   automake \
+   cmake \
+   curl \
+   libtool \
+   make \
+   ninja-build \
+   patch \
+   python3-pip \
+   unzip \
+   virtualenv
 ```
 
-### Build it
+#### Install Clang/LLVM
 
-```bash
-bazel build -c opt //:nighthawk
+Note that depending on the chosen Ubuntu version, you may need to manually
+install a never version of Clang/LLVM. The installed version of Clang can be
+verified by running:
+```
+clang -v
+```
+
+If you do need to install a newer version, be sure to use Ubuntu's
+`update-alternatives` or a similar approach to switch to using the newer
+Clang/LLVM. See [issue#832](https://github.com/envoyproxy/nighthawk/issues/832)
+for one possible approach.
+
+Run the following commands to install Clang/LLVM.
+```
+sudo apt install -y lld clang llvm lld lldb
+sudo apt install -y clang-{format,tidy,tools} clang-doc clang-examples
+```
+
+#### Install Bazelisk instead of bazel
+
+[Bazelisk](https://github.com/bazelbuild/bazelisk) is recommended, since it
+automatically chooses and downloads the appropriate Bazel version.
+
+Run the following to install Bazelisk.
 ```
+sudo wget -O /usr/local/bin/bazel https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-$([ $(uname -m) = "aarch64" ] && echo "arm64" || echo "amd64")
+sudo chmod +x /usr/local/bin/bazel
+```
+
+#### Clone Nighthawk and setup Clang as the compiler
+
+Run the following to clone the Nighthawk repository and instruct Bazel to use
+Clang.
+```
+git clone https://github.com/envoyproxy/nighthawk
+cd nighthawk/
+echo "build --config=clang" >> user.bazelrc
+```
+
+#### Build and testing  Nighthawk
+
+You can now use the CI script to build Nighthawk.
+```
+ci/do_ci.sh build
+```
+
+Or to execute its tests.
+```
+ci/do_ci.sh test
+```
+
+Note that after building completes, the Nighthawk binaries are located in the
+`bazel-bin/` directory located at the root of the cloned Nighthawk repository.
+
+## Using the Nighthawk client CLI
 
-### Using the CLI
+For using the Nighthawk test server, see [here](source/server/README.md).
 
 ```bash
 ➜ bazel-bin/nighthawk_client --help