-# nailing-cargo: wrapper to use unpublished local crates
-#
-# Copyright (C) 2019-2020 Ian Jackson
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as
-# published by the Free Software Foundation, either version 3 of the
-# License, or (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU Affero General Public License for more details.
-#
-# You should have received a copy of the GNU Affero General Public License
-# along with this program. If not, see <http://www.gnu.org/licenses/>.
-
-# example usages:
-# ../nailing-cargo/nailing-cargo make
-# ../nailing-cargo/nailing-cargo cargo build
-
-# Why do we need this ?
-#
-# https://github.com/rust-lang/cargo/issues/6713
-# https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate
-# https://github.com/rust-lang/cargo/issues/1481
-
-# Options:
-# -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
-#
-# -T | --no-cargo-target-arg
-# -t | --cargo-target-arg
-# Suppress --target (or un-suppress it). Only useful with -m.
-# Done automatically when nailing-cargo sees that the cargo
-# subcommand is one which needs it, eg `fetch'.
-#
-# 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> = ... }
-#
-# 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 ?
-#
-# 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)
-