From 4c8ca6af0023b0b3a0bf5011b24233d7d0a338e2 Mon Sep 17 00:00:00 2001
From: David Sankel <dsankel@adobe.com>
Date: Mon, 21 Nov 2022 19:56:02 -0500
Subject: [PATCH] Fix Bazel build instructions and elaborated them

The `bazel` call that utilized a local LLVM installation failed with
linker errors because the link order of LLVM libraries wasn't in
dependency order. The fix is to utilize LLD via the `-fuse-ld` flag. LLD,
unlike traditional Unix-like linkers, allows for reverse dependencies
(aka backrefs. See the --warn-backrefs option). Note that the `-fuse-id`
flag was being used for the Bazel-provided LLVM installation configuration.

Several other changes were made:
* The build system was broken into two sections: install dependencies and
  build crubit. This was done since the former usually need be done only
  once.
* Modified the installation instructions to install bazelisk as the
  system installation of bazel was incorrect (the package name is actually
  bazel-bootstrap) and, even if it were correct, would install a version
  that is too old.
* Clarified the two build options and the reasons why one would prefer
  one to the other.
* Modified the local LLVM option to build and use `lld`. This reduces
  variance of tooling used to build this project.
* Added `$LLVM_INSTALL_PATH/bin` to the `PATH` so this compiler is selected
  instead of any system installations.
---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 39 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index ca79516a..cd817591 100644
--- a/README.md
+++ b/README.md
@@ -7,24 +7,54 @@ Extremely experimental interop tooling for C++ and Rust.
 Please don't use, this is an experiment and we don't yet know where will it take
 us. There will be breaking changes without warning. Unfortunately, we can't take contributions at this point.
 
-## Building Crubit
+## Build
+
+There are two supported ways to build Crubit.
+
+* **Option 1: Local LLVM installation**. This option is recommended for most use cases. It involves building a local copy of LLVM code which will enable one to easily stay in sync with the latest version.
+
+* **Option 2: Basel provided LLVM installation**. This option is recommended for developers that need to track an older version of LLVM.
+
+### Install system dependencies
+
+#### Install Bazelisk
+
+Install Bazelisk following [these instructions](https://github.com/bazelbuild/bazelisk/blob/master/README.md).
+
+#### Install system packages
 
 ```
-$ apt install clang lld bazel
-$ git clone git@github.com:google/crubit.git
-$ cd crubit
-$ bazel build --linkopt=-fuse-ld=/usr/bin/ld.lld //rs_bindings_from_cc:rs_bindings_from_cc_impl
+$ apt install clang lld
 ```
 
-### Using a prebuilt LLVM tree
+#### Build local LLVM installation (**Option 1** only)
 
 ```
 $ git clone https://github.com/llvm/llvm-project
 $ cd llvm-project
-$ CC=clang CXX=clang++ cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS='clang' -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install
+$ CC=clang CXX=clang++ cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS='clang;lld' -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install
 $ cmake --build build -j
 $ # wait...
 $ cmake --install build
-$ cd ../crubit
-$ LLVM_INSTALL_PATH=../llvm-project/install bazel build //rs_bindings_from_cc:rs_bindings_from_cc_impl
+$ cd ..
+```
+
+### Build Crubit
+
+#### Build with local LLVM installation (**Option 1** only)
+
+```
+$ export LLVM_INSTALL_PATH=$PWD/llvm-project/install
+$ export PATH="$LLVM_INSTALL_PATH/bin:$PATH"
+$ cd crubit
+$ bazel build --linkopt=-fuse-ld=$LLVM_INSTALL_PATH/bin/ld.lld //rs_bindings_from_cc:rs_bindings_from_cc_impl
+```
+
+#### Build with Basel provided LLVM installation (**Option 2** only)
+
+```
+$ apt install clang lld bazel
+$ git clone git@github.com:google/crubit.git
+$ cd crubit
+$ bazel build --linkopt=-fuse-ld=/usr/bin/ld.lld //rs_bindings_from_cc:rs_bindings_from_cc_impl
 ```