nailing-cargo: Docs.

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

diff --git a/nailing-cargo b/nailing-cargo
index 48f0d3db56275257c51d300193e537d195dd0045..1bca9d048a2751fee7b1ba0a8aa2818d0ef77fee 100755 (executable)
--- a/nailing-cargo
+++ b/nailing-cargo
@@ -28,9 +28,50 @@
 #  https://github.com/rust-lang/cargo/issues/1481
 
 # Options:
-#    TBD
+#    -v   Increase verbosity.  Default is 1.
+#    -q   Set verbosity ot 0.
+#    -D   Increase amount of debugging dump.
+#
+#    -n   "No action": stop after writing Cargo.toml.nailing~
+#         everywhere, and do not run any build command.
+#
+#    -T<arch> --target=<arch>
+#         Specify target architecture.  If <arch> starts with a
+#         capital ascii letter, is an alias for some other arch
+#         looked up in Cargo.nail and then in the builtin list:
+#           RPI   arm-unknown-linux-gnueabihf
+#         Translates to a --target= option to the ultimate command,
+#         unless that is a cargo subcommand which would reject it.
+#
+#    -u | --cargo-lock-update
+#    -U | --no-cargo-lock-update
+#         Arranges to do a dance to allow Cargo.lock (or
+#         alternative) to be updated in the source directory.
+#
+#         The Cargo.lock and Cargo.toml are copied to the build
+#         directory along with a skeleton just big enough to fool
+#         cargo.  After cargo has run, the resulting Cargo.lock is
+#         copied back to the source tree.
+#
+#         Makes no sense with in-tree builds.
+#
+#         Default is no update unless the ultimate command is a
+#         cargo subcommand which we know needs it.
+#
+#    -m | --cargo-manifest-args
+#    -M | --no-cargo-manifest-args
+#         Controls whether we add cargo command line options
+#         relating to finding Cargo.toml, to the command to
+#         run.
+#
+#         Default is true if we are doing an out-of- tree build,
+#         unless we are updating the Cargo.lock (in which case the
+#         only relevant files are to be found in the build directory).
+#
+#         The arguments are
+#             --manifest-path=<path/to/Cargo.toml>
+#             --locked --target-dir=target
 #
-
 # Cargo.nail:
 #
 #    # Adds each <subdir> to the list of directories whose
@@ -104,7 +145,12 @@
 #     Ideally should be configurable, and also perhaps be able
 #     to combine multiple Cargo.nail files ?
 #
-# Env vars:
+# Env vars we pass to the command:
+#   NAILINGCARGO_WORKSPHERE     absolute path of invocation ..
+#   NAILINGCARGO_MANIFEST_DIR   absolute path of invocation .
+#   NAILINGCARGO_BUILDSPHERE    only if out of tree: abs parent of build dir
+#   NAILINGCARGO_BUILD_DIR      absolute path of build dir (even if = src)
+
 
 our $self;