X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=README.md;h=78acb9e831384e14665abc74d6f5afcbdccb11b1;hb=b3f50653a32ee3d398d141280cdc9d7f93402ed0;hp=e7a5c52aa6a773d221fab3e2274a3cd83bb67ab6;hpb=dde9228e1cdd523811999300e22f8db4d6cdbe71;p=nailing-cargo.git diff --git a/README.md b/README.md index e7a5c52..78acb9e 100644 --- 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`. +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 ------------------------------ @@ -242,7 +248,7 @@ rules when interpreting its command line: treated as the start of the ``. * `` 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 @@ -274,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` | `--target=` Specify target architecture. @@ -284,7 +293,13 @@ Options If `` 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` @@ -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`. - 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. @@ -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.) + * `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=`; 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 @@ -363,9 +387,74 @@ Options * `!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`. + * `--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 @@ -374,10 +463,38 @@ Options `.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. - * `--man` | `--manual`: Format this manual into html using `pandoc` - and display it with `w3m`. + * `--doc` | `--man` | `--manual`: Format this manual into html using + `pandoc` and display it with `w3m`. Environment of the build command -------------------------------- @@ -541,6 +658,11 @@ To control use of alternative `Cargo.lock` filename, use the section be just the local username (meaning `@localhost`), or `@`. + * `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 ------------------------------------------