with `Cargo.nail` files which imply overlapping sets of package
directories, things will go Badly Wrong.
+ * Many real-world packages do not support out-of-tree builds
+ properly. Doing so well is not easy because cargo does not
+ provide a package with all the path information needed to do a
+ good job. Also the Rust community's infrastructure and tooling
+ does not do out-of-tree builds by default.
+
+ If you encounter such a package, `--linkfarm` will often help.
+
+ * git submodules are not supported. In theory this could perhaps be
+ improved, but it is not trivial because git submodules are badly
+ broken. If you can, avoid git submodule and use other techniques
+ instead (e.g., `git subtree`).
+
Contributing and legal
======================