From acd12d1473530d4a5c748798e555ccf97f41e789 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Mon, 11 May 2020 01:29:45 +0100
Subject: [PATCH] nailing-cargo: Docs.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---
 nailing-cargo | 83 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 75 insertions(+), 8 deletions(-)

diff --git a/nailing-cargo b/nailing-cargo
index f9d766b..48f0d3d 100755
--- a/nailing-cargo
+++ b/nailing-cargo
@@ -18,9 +18,8 @@
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 # example usages:
-#   ../nailing-cargo/nailing-caretwgo make
+#   ../nailing-cargo/nailing-cargo make
 #   ../nailing-cargo/nailing-cargo cargo build
-#   CARGO='../nailing-cargo/nailing-cargo cargo' make
 
 # Why do we need this ?
 #
@@ -28,16 +27,84 @@
 #  https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate
 #  https://github.com/rust-lang/cargo/issues/1481
 
-# Needs libtoml-perl
+# Options:
+#    TBD
+#
 
-#: Cargo.nail:
+# Cargo.nail:
+#
+#    # Adds each <subdir> to the list of directories whose
+#    # Cargo.toml is to be nailed, and also arranges to use
+#    # the package found there for other directories if
+#    # no other source of that package is evident in Cargo.nail.
+#    subdirs = [
+#      "<subdir>"
+#      ...
+#    ]
+# or:
+#    subdirs = """
+#      "<subdir>"
+#      ...
+#    """
 #
+#    # Adds <subdir> to the list of directories whose Cargo.toml
+#    # is to be nailed, and overrides any other nailing for <package>
 #    [packages]
-#    package = subdir
-#    package = { subdir = ... }
+#    <package> = <subdir>
+#    <package> = { <subdir> = ... }
+#
+# To control use of alternative Cargo.lock filename:
+#    [alt_cargolock]
+#
+#    file = true               # equivalent to "Cargo.lock.example"
+#    file = false              # disables this feature
+#    file = "<some leafname>"
+# 
+#    force = false    # default, uses alt file only if it already exists
+#    force = true     # always uses alt file; creation would make Cargo.lock
+#
+# (you can also specify just alt_cargo_lock instead of alt_cargo_lock.file)
+#
+# To enable out of tree builds:
+#    [oot]
+#    dir = "<build-directory>"    # default is Build, if use is specified
+# and then
+#    use = "really"
+#    user = "<someuser>"
+#  or
+#    use = "ssh"
+#    user = "<user>@host"         # NB must still share a filesystem!
+#  or
+#    use = "command_args"
+#    command = ["<command>", "<which works like>", "nice"]
+#  or
+#    use = "command_sh"
+#    command = ["<command>", "<which work like>", "sh -c"]
+#  or
+#    use = "null"
+#
+# Limitations:
+#
+#   Always dirties everyone's Cargo.toml, but tries to put them
+#     back (if not, running it again should fix it).  Cannnot be
+#     fixed without changes to cargo.
+#
+#   Out of tree builds require a unified filesystem view: eg,
+#     different users on the same host, NFS, or something.  This
+#     could be improved.
+#
+#   Alternative Cargo.lock file must currently be a leafname.
+#     I think this just involves review to check other values work.
+#
+#   Alternative Cargo.lock file must be on smae filesystem.
+#     This is not so easy; we would want the existing algorithm but
+#     a fallback for this case.
+#
+#   Cargo.nail unconditionally looked for in ..
+#     Ideally should be configurable, and also perhaps be able
+#     to combine multiple Cargo.nail files ?
 #
-#    [subdirs]
-#    subdir
+# Env vars:
 
 our $self;
 
-- 
2.30.2