README.md: Discussion of the scope of the local crate feature

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README.md b/README.md
index c4b414727e9794dedcdc265fa98a044254d55bd2..7db1f60225aacb7c355e6c2660bb26eea4b4006e 100644 (file)
--- a/README.md
+++ b/README.md
@@ -111,6 +111,27 @@ will be used for other massaged `Cargo.toml`s.
 
 See the [Configuration reference] for full details.
 
+Scope of nailing-cargo's local crate functionality
+--------------------------------------------------
+
+nailing-cargo's `Cargo.toml` massaging will allow you to easily build
+an interdepending set of local packages, possibly even including
+private unpublished packages, and/or locally-modified versions of
+published packages.  These local packages can freely depend on
+published packages (eg from `crates.io`) in the usual way.
+
+Compared to the correspdonding cargo feature, nailing-cargo's approach:
+(i) works even for local crates that have not been published anywhere; and
+(ii) it is a lot simpler to configure.
+
+But nailing-cargo's local crate support won't work if any non-local
+crate needs to be rebuilt against a local crate (ie, a local version
+of one of its dependencies).  If that is your requirement, either make
+local versions of the intermediate crates in the dependency graph, or
+use the cargo override facility --- see [Overriding
+Dependencies](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html)
+in the Cargo Book.
+
 Out-of-tree builds
 ==================