From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Fri, 19 Jun 2020 12:32:10 +0000 (+0100)
Subject: README.md: Config reference: oot
X-Git-Tag: nailing-cargo/1.0.0~144
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=a58a59d258e12d1a7f5bb4a4df928872634fa97a;p=nailing-cargo.git

README.md: Config reference: oot

Reported-by: Mark Wooding <mdw@distorted.org.uk>
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---

diff --git a/README.md b/README.md
index 6e55702..520f7eb 100644
--- a/README.md
+++ b/README.md
@@ -115,29 +115,17 @@ To enable out-of-tree-builds, put an `[oot]` section in your
 `Cargo.nail` or one of nailing-cargo's other config files.
 In that section, specify at least `use`.
 
-The primary config keys here are:
+Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
+pointing to to your build area.
 
-  * `dir`: The build directory.  If relative, it is relative to the
-   parent of the invocation directory (and could be a symlink then).
-   Default is `Build` (assuming `use` is specified).
-
-  * `use`: How to become the build user.  Needs to be combined
-    with other setting(s):
-
-    * `ssh`: Use ssh.  `user` must be given as well and can be
-       a username on localhost, or the `<user>@<host>`
-       argument to ssh.
-
-    * `command_args`: `command` must be specified as a list,
-       specifying a command and arguments which work like `nice`.
-
-    * `command_sh`: `command` must be specified as a list,
-       specifying a command and arguments which work like `sh -c`.
-
-    * `null`: Run builds as the same user.
-
-    * `really`: Use `really` from `chiark-really.deb`.
-       `user` must be given as well.
+For example,
+```
+[oot]
+use='ssh'
+user='rustcargo'
+```
+will have nailing-cargo run `ssh rustcargo@localhost` to
+run build commands.
 
 Target architecture convenience aliases
 =======================================
@@ -307,6 +295,36 @@ To control use of alternative `Cargo.lock` filename, use the section
 
   * `force = true`: Always uses the alternative filename.
 
+`[oot]`: Out-of-tree build support
+----------------------------------
+
+  * `dir`: The build directory.  If relative, it is relative to the
+   parent of the invocation directory (and could be a symlink then).
+   Default is `Build` (assuming `use` is specified).
+
+  * `use`: How to become the build user.  Needs to be combined
+    with other setting(s):
+
+    * `ssh`: Use ssh.  `user` must be given as well and can be
+       a username on localhost, or the `<user>@<host>`
+       argument to ssh.
+
+    * `command_args`: `command` must be specified as a list,
+       specifying a command and arguments which work like `nice`.
+
+    * `command_sh`: `command` must be specified as a list,
+       specifying a command and arguments which work like `sh -c`.
+
+    * `null`: Run builds as the same user.
+
+    * `really`: Use `really` from `chiark-really.deb`.
+       `user` must be given as well.
+
+ * `command`: The command to run for `command_sh` or `command_args`.
+
+ * `user`: The local username for `really` and `ssh`, or
+   `<user>@<host>` for `ssh`.
+
 Running the command
 ===================