# 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 ?
#
# 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;