From 87d73f19ad6efc9749daaad62e1ca6b3cf47fe25 Mon Sep 17 00:00:00 2001
From: Jed Brown <jed@jedbrown.org>
Date: Sun, 27 Nov 2022 11:36:49 -0700
Subject: [PATCH] README: update for library use and new documentation

---
 README.md | 153 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 103 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index 10e1fbf..90cdc82 100644
--- a/README.md
+++ b/README.md
@@ -18,9 +18,17 @@ for starting MPI jobs.
 cargo install cargo-mpirun
 ```
 
+### Library
+To use `cargo-mpirun` as a library, skip the install command above and edit your `Cargo.toml` to include
+
+``` toml
+[dependencies]
+cargo-mpirun = "0.2.0"
+```
+
 ## Related Projects
 If you're interested in writing MPI applications in Rust, take a look at
-[rsmpi](https://github.com/bsteinb/rsmpi). It provides a zero-overhead, safe
+[rsmpi](https://github.com/rsmpi/rsmpi). It provides a zero-overhead, safe
 abstraction over the C MPI APIs.
 
 ## Usage
@@ -56,52 +64,92 @@ cargo mpirun --example <example>
 
 ### Full Usage
 ```
-cargo-mpirun 0.1
-Andrew Gaspar <andrew.gaspar@outlook.com>
-Run the main binary of the local package (src/main.rs) using mpiexec.
-
-USAGE:
-    cargo mpirun [OPTIONS]
-
-OPTIONS:
-    -n, --np <num_processes>          Number of processes to run
-    -N, --npernode <num_processes>
-            Launch num_processes per node on all allocated nodes
-
-        --oversubscribe
-            Nodes are allowed to be oversubscribed, even on a managed system,
-            and overloading of processing elements
-        --bin <NAME>                  Name of the bin target to run
-        --example <NAME>              Name of the example target to run
-    -p, --package <NAME>              Package with the target to run
-    -j, --jobs <N>
-            Number of parallel jobs, defaults to # of CPUs
-
-        --release
-            Build artifacts in release mode, with optimizations
-
-        --features <FEATURE>...
-            Space-separated list of features to also build
-
-        --all-features                Build all available features
-        --no-default-features         Do not build the `default` feature
-        --target <TRIPLE>             Build for the target triple
-        --manifest-path <PATH>        Path to the manifest to execute
-    -v, --verbose
-            Use verbose output (-vv very verbose/build.rs output)
-
-    -q, --quiet                       No output printed to stdout
-        --color <WHEN>                Coloring [values: auto, always, never]
-        --message-format <FMT>
-            Error format [default: human]  [values: human, json]
-
-        --frozen
-            Require Cargo.lock and cache are up to date
-
-        --locked                      Require Cargo.lock is up to date
-    -Z <FLAG>...                      Unstable (nightly-only) flags to Cargo
-    -h, --help                        Prints help information
-    -V, --version                     Prints version information
+Run a binary or example of the local package using mpiexec.
+
+Usage: cargo mpirun [OPTIONS] [-- <ARGS>...]
+
+Arguments:
+  [ARGS]...
+          Arguments for mpiexec
+
+Options:
+  -n, --np <NUM_PROCESSES>
+          Number of processes
+
+  -N, --npernode <NUM_PROCESSES_PER_NODE>
+          Number of processes per node on all allocated nodes
+
+      --mpiexec <MPIEXEC>
+          Command to execute in place of `mpiexec` (see also MPIEXEC and MPI_HOME)
+
+      --oversubscribe
+          Allow nodes to be oversubscribed (may cause severe performance degradation)
+
+      --bin <BIN>
+          Name of bin target to run
+
+      --example <EXAMPLE>
+          Name of example target to run
+
+  -p, --package <PACKAGE>
+          Package with the target to run
+
+  -j, --jobs <JOBS>
+          Number of parallel build jobs; default to # of CPUs
+
+      --release
+          Build artifacts in release mode, with optimizations
+
+      --offline
+          Build without accessing the network
+
+      --features <FEATURES>
+          Space or comma separated list of features to activate
+
+      --all-features
+          Build all available features
+
+      --no-default-features
+          Do not build the `default` feature
+
+      --target <TRIPLE>
+          Build for the target triple
+
+      --target-dir <DIRECTORY>
+          Directory for all generated artifacts
+
+      --config <KEY=VAL>
+          Override a configuration value
+
+      --manifest-path <MANIFEST_PATH>
+          Path to the manifest to execute
+
+  -v, --verbose...
+          Use verbose output (`-vv` very verbose/build.rs output)
+
+  -q, --quiet
+          No output printed to stdout
+
+      --color <WHEN>
+          Possible values:
+          - auto:   Use colored output if writing to a terminal/TTY
+          - always: Always use colored output
+          - never:  Never use colored output
+
+      --frozen
+          Require Cargo.lock and cache are up to date
+
+      --locked
+          Require Cargo.lock is up to date
+
+  -Z <FLAG>
+          Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+
+  -h, --help
+          Print help information (use `-h` for a summary)
+
+  -V, --version
+          Print version information
 
 If neither `--bin` nor `--example` are given, then if the project only has one
 bin target it will be run. Otherwise `--bin` specifies the bin target to run,
@@ -109,6 +157,11 @@ and `--example` specifies the example target to run. At most one of `--bin` or
 `--example` can be provided.
 
 All of the trailing arguments are passed to mpiexec. If you're passing arguments
-to both Cargo and the binary, the ones after `--` go to mpiexec, the ones before
-go to Cargo.
-```
\ No newline at end of file
+to both Cargo and the binary, the ones after `--` go to mpiexec, the
+ones before go to Cargo.
+
+Environment variables:
+
+  MPIEXEC  - Command to use for mpiexec
+  MPI_HOME - Find mpiexec in $MPI_HOME/bin/mpiexec
+```