docs: update build_instructions.md

immunant · Mar 13, 2024 · b9ef3ea · b9ef3ea
1 parent b4adc8c
commit b9ef3ea
Showing 1 changed file with 17 additions and 8 deletions.
diff --git a/docs/build_instructions.md b/docs/build_instructions.md
@@ -14,21 +14,30 @@ rustup install nightly
 
 ## Configure with CMake
 
-*Note*: Adjust paths to your version of Clang/LLVM
+*Note*: Adjust paths to your version of Clang/LLVM or using `llvm-config --cmakedir`
 
 ```
 mkdir build && pushd build
 cmake ..                                        \
-            -DClang_DIR=/usr/lib/cmake/clang-12 \
-            -DLLVM_DIR=/usr/lib/llvm-12/cmake   \
+            -DClang_DIR=/usr/lib/cmake/clang-15 \
+            -DLLVM_DIR=/usr/lib/cmake/llvm-15   \
             -DLLVM_EXTERNAL_LIT=`which lit`     \
             -G Ninja
 ```
 
-## Build and run the tests
+### Notable CMake variables
 
-*Note*: Pass `-v` to ninja to see build commands and output from failing tests.
+- `LIBIA2_DEBUG` - Adds additional runtime assertions to validate control-flow.
+- `LIBIA2_AARCH64` - Builds the runtime and tests for Aarch64 using MTE instead of x86-64 with MPK. Tools are still built for the host.
+- `CMAKE_TOOLCHAIN_FILE` - Typically set to `cmake/aarch64-toolchain.cmake` to build for Aarch64 using GCC. This also sets LIBIA2_AARCH64.
 
-```
-ninja check-ia2
-```
+## CMake targets
+
+- `check` - builds and runs the test suite. Pass `-v` to ninja to see build commands and output from failing tests.
+- `ia2-rewriter` - builds the source-code rewriter. Depends on libclang-dev and llvm-dev.
+- `pad-tls` - builds a script for padding ELF headers for TLS segments. Only required for compartmentalized DSOs that use thread-local storage.
+- `libia2` - builds the runtime as a static library. This does not include call gate transitions as those are program-specific and generated by the rewriter. 
+- `partition-alloc` - builds the compartment-aware shim for Chromium's PartitionAlloc allocator.
+- `ia2-sandbox` - builds the syscall tracer.
+
+Tests are enumerated in `tests/CMakeLists.txt`. To build a specific test use `$TEST_main_wrapped` as the target. See the [`directory structure doc`](docs/directory_structure.md) for an overview of the rest of the repo's contents.