From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 21 Jun 2020 19:46:38 +0000 (+0100)
Subject: README.md: Discussion of the scope of the local crate feature
X-Git-Tag: nailing-cargo/1.0.0~99
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=1149e906959139fb4ef20ad90380e17b7cc5f2d2;p=nailing-cargo.git

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 c4b4147..7db1f60 100644
--- 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
 ==================