X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=README.md;h=78acb9e831384e14665abc74d6f5afcbdccb11b1;hb=b3f50653a32ee3d398d141280cdc9d7f93402ed0;hp=c4b414727e9794dedcdc265fa98a044254d55bd2;hpb=06077b9b33f102ee6767ee9560b111cfb3bf05bd;p=nailing-cargo.git

diff --git a/README.md b/README.md
index c4b4147..78acb9e 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,28 @@ containing a list of subdirectory names one per line.  In each of
 these directories `Cargo.toml` will be massaged, and the package there
 will be used for other massaged `Cargo.toml`s.
 
-See the [Configuration reference] for full details.
+See the [Configuration reference](#configuration-reference) for full details.
+
+Scope of nailing-cargo's local crate functionality
+--------------------------------------------------
+
+nailing-cargo's `Cargo.toml` massaging will allow you to easily build
+an interdepending set of local packages, possibly even including
+private unpublished packages, and/or locally-modified versions of
+published packages.  These local packages can freely depend on
+published packages (eg from `crates.io`) in the usual way.
+
+Compared to the corresponding cargo feature, nailing-cargo's approach:
+(i) works even for local crates that have not been published anywhere; and
+(ii) is a lot simpler to configure.
+
+But nailing-cargo's local crate support won't work if any non-local
+crate needs to be rebuilt against a local crate (ie, a local version
+of one of its dependencies).  If that is your requirement, either make
+local versions of the intermediate crates in the dependency graph, or
+use the cargo override facility --- see [Overriding
+Dependencies](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html)
+in the Cargo Book.
 
 Out-of-tree builds
 ==================
@@ -136,6 +157,12 @@ nailing-cargo arranges this for you.  You can either put this file in
 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
 save it as something like `Cargo.lock.example`.
 
+Depending on the circumstances, nailing-cargo uses a variety of
+strategies, including `--manifest-path` options, and linkfarming, to
+make out of tree builds.  Some crates don't natively support
+out-of-tree builds, in which case passing a `--linkfarm` option to
+nailing-cargo can be helpful.
+
 Configuring out-of-tree builds
 ------------------------------
 
@@ -180,7 +207,7 @@ If you disagree with my opinion, write `misc.online=true` in your
 nailing-cargo configuration.  `misc.online=false`, and command line
 options, are also available, for overriding.
 
-If you agree, then you may wish to use `nailing-cargo
+If you agree with me, you may wish to use `nailing-cargo
 generate-lockfile`, which can update (even an existing) `Cargo.lock`
 without going online, instead of `update`.
 
@@ -196,7 +223,7 @@ Usages
 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
 ```
 Ususally the `--` is not needed.  (It should generally be passed by
-programs which wrap nailing-cargo.  See [Invocation argument disambiguation rules], below.)
+programs which wrap nailing-cargo.  See [Invocation argument disambiguation rules](#invocation-argument-disambiguation-rules), below.)
 
 In usage 1, nailing-cargo runs `cargo` (from `PATH`).  In the usage 2
 nailing-cargo runs `<cargo>`.  In both these cases it adds its own
@@ -221,7 +248,7 @@ rules when interpreting its command line:
     treated as the start of the `<cargo-opts>`.
 
   * `<cargo-opts>` are terminated by `--` (which is removed) or the
-    first argument which does not start with a `-`.
+    first argument which does not start with a `-` or `+`.
 
     (It is not possible to get nailing-cargo to pass the value `--`
     as a separate argument to a cargo global option, but cargo global
@@ -253,6 +280,9 @@ Options
   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
        everywhere, and do not run any build command.
 
+  * `-f` | `--force`: Force going ahead even if problems are likely.
+    (E.g., due to missing `-E` option.)
+
   * `-T<arch>` | `--target=<arch>`
 
     Specify target architecture.
@@ -263,7 +293,13 @@ Options
     If `<arch>` starts with a capital ascii letter, it is an alias
     for some other arch: it is looked up in the configuration, and
     then in the builtin arch alias list.  The builtin list is
-    equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
+    equivalent to:
+
+```
+[arch]
+RPI="arm-unknown-linux-gnueabihf"
+WASM="wasm32-unknown-unknown"
+```
 
   * `-o` | `--online` | `-O` | `--offline`
 
@@ -281,8 +317,8 @@ Options
 
     With this enabled, in an out-of-tree build 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.
+    linkfarm, to fool cargo.  After cargo has run, the resulting
+    `Cargo.lock` is copied back to the source tree.
 
     Default is no update unless the whole point of the cargo
     subcommand is to update `Cargo.lock`.
@@ -298,7 +334,7 @@ Options
     after the build command (usage 3).
 
     The cargo options are in any case also passed in the
-    environment - see [Environment of the build command].
+    environment - see [Environment of the build command](#environment-of-the-build-command).
 
     The default is to pass cargo options if the command line
     parsing yielded a cargo command and options (usages 1 and 2),
@@ -312,8 +348,13 @@ Options
     options to pass to cargo, whether cargo needs to be online, and
     whether cargo might want to update `Cargo.lock`.
 
-    nailing-cargo knows about `update`, `generate-lockfile` and
-    `fetch`; all other subcommands are (silently) treated the same way
+    nailing-cargo knows about the following commands:
+     * `fetch`
+     * `fmt`
+     * `generate-lockfile`
+     * `update`
+
+    All other subcommands are (silently) treated the same way
     as `build` (ie, no subcommand properties).  See
     `--subcommand-props` for more detail about how the
     subcommand affects nailing-cargo's behaviour.
@@ -329,8 +370,12 @@ Options
 
     * `lock_update`: cargo will want to update `Cargo.lock`.  (The `-u` and `-U` options override this.)
     * `online`: this subcommand makes no sense to run offline.  (The `-o` and `-O` options, and the configuration, can override this.)
+    * `edits`: The purpose of this subcommand is to edit the source tree.  Imples that `--edit-sources` is necessary (unless `--force`).
+    * `creates`: The purpose of this subcommand is to edit the source tree and create new files in it.  Imples that `-EE` (`--edit-sources`, twice) is necessary (unless `--force`).
     * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
     * `!target-dir`: cargo would reject `--target-dir`, so don't pass it.  (Usually we pass `--target-dir=target` when we pass `--manifest-path`, since cargo's default is `target` in the same directory as `Cargo.toml`.)
+    * `linkfarm-shallow`: Make the default be `--linkfarm=shallow`.  This is the default for `miri` and can also be used for other subcommands which do not understandg `--manifest-path` properly.
+    * `linkfarm-gitclean`: Make the defaults be `--linkfarm=git` and `--preclean-build=src`.
 
     There are also some properties which should not be needed, but are
     provided for completeness.  Do not use these to solve the problem
@@ -341,6 +386,116 @@ Options
     * `!locked`: cargo would reject `--locked`, so don't pass it.  Hazardous.
     * `!offline`: the build command would reject `--offline`, so never pass it.  *Not* overridden by configuration or command line.
 
+
+  * `--linkfarm[=no|shallow|git|full]`: Override nailing-cargo's
+    approach to out-of-tree builds.  Normally nailing-cargo chooses
+    automatically whether to make a linkfarm, and precisely what kind
+    of linkfarm, based on the cargo subcommand.  The linkfarm styles
+    are:
+
+    * `no`: Do not make a linkfarm; pass a `--manifest-path` option
+      pointing to the actual source directory.  This is the default
+      for most cargo commands.
+
+    * `shallow`: Symlink top-level objects in the source directory,
+      including whole subdirectories.  This the default when
+      nailing-cargo thinks cargo is going to update `Cargo.lock`.
+
+    * `git`: Make a deep linkfarm, with subdirectories.  Symlink
+      those objects tracked by git.  This is the default for
+      `cargo publish`.
+
+    * `full`: Make a deep linkfarm and symlink every nondirectory found
+      in the source tree.  This will including all sorts of junk,
+      including for example editor backup files.
+
+    Whenever nailing-cargo linkfarms, old symlinks pointing back to
+    the source tree are deleted.  In each case, `Cargo.lock` is not
+    symlinked, but copied.  If nailing-cargo expects cargo to update
+    `Cargo.lock`, it will copy it back to the source tree afterwards.
+    Just `--linkfarm` is the same as `--linkfarm=git`.
+
+  * `--edit | --edit-sources | -E`: Permits the cargo command to edit
+    sources in the source tree.  This is achieved by *copying* the
+    entire source tree (all files tracked by git) into the destination
+    directory, and then copying back all changed files.  *Only git
+    tracked filles* can be edited by the cargo command; edits to
+    other files, and creation of new files, will be ignored.
+
+    When this option is repeated (**`-EE`**), the cargo subcommand can
+    create new files including dotfiles (but nothing in the toplevel
+    `target` and nothing called `.git`).  (This also enables
+    `--preclean=src` by default.)
+
+    If you are running out of tree builds for privsep reasons, you
+    should use git to review the edits made by the cargo command and
+    either stage and commit them, or reject them.
+
+    This option is overridden by a subsequent `--linkfarm` options.
+
+    `-E` or `-f` is needed for `nailing-cargo fmt`.  `-EE` or `-f` is
+    needed for `nailing-cargo init`.  (`-E` is never the default.)
+
+  * `--just-linkfarm[=shallow|git|full]`: Make the out-of-tree
+    linkfarm as if for `--cargo-lock-update`, but do not actually run
+    any command, nor try to copy back a a generated `Cargo.lock`.
+    Forces `--keep-linkfarm` (even if the contrary is also specified).
+
+    With a linkfarming mode, overrides (and is overridden by)
+    `--linkfarm=`.  Without a linkfarming mode, and without
+    `--linkfarm`, the default is `shallow`.
+
+  * `--keep-linkfarm` | `--clean-linkfarm`: When doing an out-of-tree
+    lockfile update, controls whether the linkfarm is kept afterwards.
+    Overrides the `oot.clean` config option.  (Default: keep.)
+
+  * `--[no-]preclean-build[=no|src|full]`: When doing an out-of-tree
+    build, controls whether the build directory is purged of leftover
+    contents *before* the build is run.  The usual default is `no`.
+    For `cargo publish`, the default is `src`, which deletes
+    everything except the directory `target`.  `full` means to clean
+    out that too.
+
+  * `--leave-nailed`: At the end, leave all the `Cargo.toml` files in
+    their edited state, rather than (trying to) clean them up.  To
+    clean this up later, run `nailing-cargo` again without this option.
+    Without this option, the nailed versions are left in
+     `.Cargo.toml.nailed~`, so you only need this if you want to run
+    cargo by hand or something.
+
+  * `--just-run`: Execute the specified command (perhaps concurrently
+    with other commands), but do not manipulate any of Cargo's
+    metadata fiules.  Useful in out of tree mode to invoke a non-cargo
+    command in the build environment.  Implies `--no-nail`,
+    `--no-cargo-lock-manip` and `--no-concurrency-lock` (overrideable
+    by later occurrences of the corresponding opposite options).
+    Hazardous if the command is actually cargo, or will run cargo.
+
+  * `--no-nail` | `--nail` (default): Whether to actually nail - ie,
+    whether to actually modify any `Cargo.toml`s while running the
+    command.  This can be useful, e.g., in out-of-tree mode with
+    commands that don't actually invoke cargo.  Consider passingm
+    `--no-lock` too.
+
+  * `--no-cargo-lock-manip` | `--cargo-lock-manip` (default):
+    Whether to manipulate `Cargo.lock`.  For example, whether to copy
+    it to the build tree and back (in out of tree mode) and whether to
+    rename it from an alternative lockfile name, and put it back.
+    Overrides `-u` etc.
+
+  * `--no-concurrency-lock` | `--concurrency-lock` (default): Whether
+    to take the nailing-cargo lock.  Some kind of protection against
+    concurrent operation is necessary to prevent multiple instances of
+    nailing-cargo trashing each others' work, and possibly mangling
+    your `Cargo.toml`s, `Cargo.lock`, etc., so `--no-concurrency-lock`
+    is dangerous unless you take other measures against concurrent
+    execution.
+
+  * `-h` | `--help`: Print usage summary.
+
+  * `--doc` | `--man` | `--manual`: Format this manual into html using
+    `pandoc` and display it with `w3m`.
+
 Environment of the build command
 --------------------------------
 
@@ -503,6 +658,11 @@ To control use of alternative `Cargo.lock` filename, use the section
    be just the local username (meaning `@localhost`), or
    `<user>@<host>`.
 
+ * `clean` (boolean): When doing a `Cargo.lock` update, which involves
+   linkfarming in the build directory, whether the clean up the
+   linkfarm afterwards.  Default: `true`.  Can be overridden by
+   `--keep-linkfarm` or `--clean-linkfarm`.
+
 `[arch]`: Architecture convenience aliases
 ------------------------------------------