From c3a3d5c189841520f12e1c2450c4ea40eae28825 Mon Sep 17 00:00:00 2001
From: andrew-signal <andrew@signal.org>
Date: Wed, 23 Oct 2024 17:32:17 -0400
Subject: [PATCH] Update README to document new developer pitfalls

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 52 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e1497eb8b..3bb1c12d4 100644
--- a/README.md
+++ b/README.md
@@ -41,14 +41,31 @@ increases to the minimum supported tools versions.
 
 # Building
 
+### Toolchain Installation
+
 To build anything in this repository you must have [Rust](https://rust-lang.org) installed,
 as well as Clang, libclang, [CMake](https://cmake.org), Make, protoc, and git.
+
+#### Linux/Debian
+
 On a Debian-like system, you can get these extra dependencies through `apt`:
 
 ```shell
 $ apt-get install clang libclang-dev cmake make protobuf-compiler git
 ```
 
+#### macOS
+
+On macOS, we have a best-effort maintained script to set up the Rust toolchain you can run by:
+
+```shell
+$ bin/mac_setup.sh
+```
+
+## Rust
+
+### First Build and Test
+
 The build currently uses a specific version of the Rust nightly compiler, which
 will be downloaded automatically by cargo. To build and test the basic protocol
 libraries:
@@ -60,8 +77,24 @@ $ cargo test
 ...
 ```
 
-When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files.
-See [``acknowledgments/README.md``](acknowledgments/).
+### Additional Rust Tools
+
+The basic tools above should get you set up for most libsignal Rust development. 
+
+Eventually, you may find that you need some additional Rust tools like `cbindgen` to modify the bridges to the 
+client libraries or `taplo` for code formatting. 
+
+You should always install any Rust tools you need that may affect the build from cargo rather than from your system
+package manager (e.g. `apt` or `brew`). Package managers sometimes contain outdated versions of these tools that can break
+the build with incompatibility issues (especially cbindgen).
+
+To install the main Rust extra dependencies matching the versions we use, you can run the following commands: 
+
+```shell
+$ cargo +stable install cbindgen cargo-fuzz
+$ cargo +stable install --version "$(cat ../acknowledgments/cargo-about-version)" --locked cargo-about
+$ cargo +stable install --version "$(cat ../.taplo-cli-version)" --locked taplo-cli
+```
 
 ## Java/Android
 
@@ -89,11 +122,7 @@ $ make
 ```
 
 When exposing new APIs to Java, you will need to run `rust/bridge/jni/bin/gen_java_decl.py` in
-addition to rebuilding. This requires installing the `cbindgen` Rust tool:
-
-```shell
-$ cargo +stable install cbindgen
-```
+addition to rebuilding. This requires installing the `cbindgen` Rust tool, as detailed above. 
 
 ### Maven Central
 
@@ -172,6 +201,22 @@ the project.
 
 Signing a [CLA (Contributor License Agreement)](https://signal.org/cla/) is required for all contributions.
 
+## Code Formatting and Acknowledgments
+
+You can run the styler on the entire project by running:
+
+```shell
+just format-all
+```
+
+You can run more extensive tests as well as linters and clippy by running:
+
+```shell
+just check-pre-commit
+```
+
+When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files. See [``acknowledgments/README.md``](acknowledgments/).
+
 # Legal things
 ## Cryptography Notice