Merge pull request #218 from rust-secure-code/doc-updates

README and documentation updates for nightly

Author: Shnatsel

README.md

@@ -21,6 +21,20 @@ cargo audit bin target/release/your-project
 
 `cargo auditable` works with any Cargo command. All arguments are passed to `cargo` as-is.
 
+### On nightly Rust
+
+On nightly we can take advantage of Cargo's [native SBOM precursor](https://doc.rust-lang.org/cargo/reference/unstable.html#sbom) to record dependencies more accurately:
+
+```bash
+CARGO_BUILD_SBOM=true cargo +nightly auditable build -Z sbom --release
+```
+
+Due to [a bug in Cargo](https://github.com/rust-lang/cargo/issues/15695) you may have to `touch src/*` or `cargo clean` first if you also used `cargo auditable` without `-Z sbom` in the same project.
+
+### Through other tools
+
+If you're not calling `cargo` directly and cannot change how it's invoked, you can use `cargo auditable` as a drop-in replacement for `cargo`. See [here](REPLACING_CARGO.md) for details.
+
 ## Adoption
 
 Microsoft uses `cargo auditable` internally and maintains the [data extraction library for Go](https://github.com/microsoft/go-rustaudit).
@@ -104,4 +118,6 @@ Do not rely on SBOMs when dealing with supply chain attacks!
 
 ### What is blocking uplifting this into Cargo?
 
-The [RFC for this functionality in Cargo itself](https://github.com/rust-lang/rfcs/pull/2801) has been [postponed](https://github.com/rust-lang/rfcs/pull/2801#issuecomment-2122880841) by the Cargo team until the [more foundational SBOM RFC](https://github.com/rust-lang/rfcs/pull/3553) is implemented. That RFC has now been implemented and is available via an [unstable feature](https://doc.rust-lang.org/cargo/reference/unstable.html#sbom). cargo-auditable integrates with this: if you enable that feature and build with cargo auditable, e.g with `CARGO_BUILD_SBOM=true cargo auditable -Z sbom build` and a nightly Rust toolchain, then cargo auditable will use the SBOM precursor files generated by cargo.
+The [RFC for this functionality in Cargo itself](https://github.com/rust-lang/rfcs/pull/2801) has been [postponed](https://github.com/rust-lang/rfcs/pull/2801#issuecomment-2122880841) by the Cargo team until the [more foundational SBOM RFC](https://github.com/rust-lang/rfcs/pull/3553).
+
+That RFC has now been implemented and is available via an [unstable feature](https://doc.rust-lang.org/cargo/reference/unstable.html#sbom). This opens the door to submitting an RFC for this functionality into `cargo` itself once again.

REPLACING_CARGO.md

@@ -2,15 +2,15 @@
 
 **Note:** This document describes Unix-like systems, but similar approaches can be applied to Windows as well. Pull requests adding recipes for Windows are welcome.
 
-The recommended way is to use a shell alias:
+To use `cargo auditable` in place of `cargo` only when you call it yourself from the sell, use a shell alias:
 ```bash
 alias cargo="cargo auditable"
 ```
 When entered into the shell, it will only persist for the duration of the session. To make the change permanent, add it to your shell's configuration file (`.bashrc` for bash, `.zshrc` for zsh, `.config/fish/config.fish` for fish).
 
-## When `alias` is not an option
+## When called through other commands
 
-In some cases using shell aliases is not an option, e.g. in certain restricted build environments. In this case you can use a different approach:
+When calling other programs such as `cmake` or `maturin`, the shell alias usually isn't honored. In this case you can use a different approach:
 
 1. Run `which cargo` to locate the Cargo binary
 2. Copy the snippet provided below and replace '/path/to/cargo' with the path you got at step 1