nailing-cargo: Properly handle renamed packages

[nailing-cargo.git] / README.md

diff --git a/README.md b/README.md
index b722bb9783c6827043072743a0cf04f07cfdcf0f..78acb9e831384e14665abc74d6f5afcbdccb11b1 100644 (file)
--- a/README.md
+++ b/README.md
@@ -157,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`.
 
 `.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
 ------------------------------
 
 Configuring out-of-tree builds
 ------------------------------
 


@@ -242,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
     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
 
     (It is not possible to get nailing-cargo to pass the value `--`
     as a separate argument to a cargo global option, but cargo global


@@ -274,6 +280,9 @@ Options
   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
        everywhere, and do not run any build command.
 
   * `-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.
   * `-T<arch>` | `--target=<arch>`
 
     Specify target architecture.


@@ -284,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
     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`
 
 
   * `-o` | `--online` | `-O` | `--offline`
 


@@ -333,8 +348,13 @@ Options
     options to pass to cargo, whether cargo needs to be online, and
     whether cargo might want to update `Cargo.lock`.
 
     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.
     as `build` (ie, no subcommand properties).  See
     `--subcommand-props` for more detail about how the
     subcommand affects nailing-cargo's behaviour.


@@ -350,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.)
 
     * `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`.)
     * `!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
 
     There are also some properties which should not be needed, but are
     provided for completeness.  Do not use these to solve the problem


@@ -363,15 +387,75 @@ Options
     * `!offline`: the build command would reject `--offline`, so never pass it.  *Not* overridden by configuration or command line.
 
 
     * `!offline`: the build command would reject `--offline`, so never pass it.  *Not* overridden by configuration or command line.
 
 

-  * `--just-linkfarm`: 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).
+  * `--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.)
 
 
   * `--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.
   * `--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.