librarize and fix bugs

Cargo.toml

@@ -1,20 +1,22 @@
 [package]
 name = "cargo-mpirun"
-version = "0.1.8"
-authors = ["Andrew Gaspar <[email protected]>"]
-description = """
-    `cargo mpirun` allows you to easily build and run your MPI applications in
-    a single command. It emulates `cargo run`, allowing you to specify a \
-    target to be built and run, and cargo takes care of the rest."""
+version = "0.2.0"
+authors = ["Andrew Gaspar <[email protected]>",
+"Jed Brown <[email protected]>",]
+description = """\
+`cargo mpirun` builds and runs your MPI applications in a single command, similar to `cargo run`.\
+"""
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/AndrewGaspar/cargo-mpirun"
 categories = ["development-tools"]
 keywords = ["message-passing", "parallel", "MPI", "cargo-subcommand"]
+edition = "2021"
 
 [dependencies]
-cargo_metadata = "0.9.1"
-clap = { version = "~2.33.0", features=["yaml"] }
+cargo_metadata = "0.15.2"
+clap = { version = "4.0.27", features = ["cargo", "derive"] }
+thiserror = "1.0.37"
 
 [badges]
-travis-ci = { repository = "AndrewGaspar/cargo-mpirun", branch = "master" }
+travis-ci = { repository = "AndrewGaspar/cargo-mpirun", branch = "master" }

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,59 +64,104 @@ cargo mpirun --example <example>
 
 ### Full Usage
 ```
-cargo-mpirun 0.1
-Andrew Gaspar <[email protected]>
-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,
 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.
-```
+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
+```

examples/pid.rs

@@ -0,0 +1,4 @@
+fn main() {
+    let name = std::env::args().next().unwrap();
+    println!("{}: {}", name, std::process::id());
+}

src/args.rs

@@ -0,0 +1,108 @@
+#[derive(Debug, Default, clap::Args)]
+#[command(
+    author,
+    version,
+    about = "Run a binary or example of the local package using mpiexec.",
+    after_help = "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,
+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.
+
+Environment variables:
+
+  MPIEXEC  - Command to use for mpiexec
+  MPI_HOME - Find mpiexec in $MPI_HOME/bin/mpiexec
+"
+)]
+pub struct Args {
+    /// Number of processes
+    #[arg(
+        short = 'n',
+        long = "np",
+        // Open MPI's mpiexec uses number of physical cores by default; MPICH
+        // uses 1, srun uses number configured in sbatch.
+        value_parser = clap::value_parser!(u32).range(1..)
+    )]
+    pub num_processes: Option<u32>,
+    #[arg(
+        short = 'N',
+        long = "npernode",
+        help = "Number of processes per node on all allocated nodes",
+        value_parser = clap::value_parser!(u32).range(1..)
+    )]
+    pub num_processes_per_node: Option<u32>,
+    /// Command to execute in place of `mpiexec` (see also MPIEXEC and MPI_HOME)
+    #[arg(long)]
+    pub mpiexec: Option<String>,
+    /// Allow nodes to be oversubscribed (may cause severe performance degradation)
+    #[arg(long)]
+    pub oversubscribe: bool,
+    /// Name of bin target to run
+    #[arg(long, group = "exec-args")]
+    pub bin: Option<String>,
+    /// Name of example target to run
+    #[arg(long, group = "exec-args")]
+    pub example: Option<String>,
+    /// Package with the target to run
+    #[arg(short = 'p', long)]
+    pub package: Option<String>,
+    /// Number of parallel build jobs; default to # of CPUs
+    #[arg(short = 'j', long, value_parser = clap::value_parser!(u32).range(1..))]
+    pub jobs: Option<u32>,
+    /// Build artifacts in release mode, with optimizations
+    #[arg(long)]
+    pub release: bool,
+    /// Build without accessing the network
+    #[arg(long)]
+    pub offline: bool,
+    /// Space or comma separated list of features to activate
+    #[arg(long)]
+    pub features: Option<String>,
+    /// Build all available features
+    #[arg(long)]
+    pub all_features: bool,
+    /// Do not build the `default` feature
+    #[arg(long)]
+    pub no_default_features: bool,
+    /// Build for the target triple
+    #[arg(long, value_name = "TRIPLE")]
+    pub target: Option<String>,
+    /// Directory for all generated artifacts
+    #[arg(long, value_name = "DIRECTORY")]
+    pub target_dir: Option<String>,
+    /// Override a configuration value
+    #[arg(long, value_name = "KEY=VAL")]
+    pub config: Vec<String>,
+    /// Path to the manifest to execute
+    #[arg(long)]
+    pub manifest_path: Option<std::path::PathBuf>,
+    /// Use verbose output (`-vv` very verbose/build.rs output)
+    #[arg(
+        short = 'v',
+        long,
+        action = clap::ArgAction::Count,
+    )]
+    pub verbose: u8,
+    /// No output printed to stdout
+    #[arg(short = 'q', long, conflicts_with = "verbose")]
+    pub quiet: bool,
+
+    #[arg(long, value_name = "WHEN")]
+    pub color: Option<clap::ColorChoice>,
+    /// Require Cargo.lock and cache are up to date
+    #[arg(long)]
+    pub frozen: bool,
+    /// Require Cargo.lock is up to date
+    #[arg(long)]
+    pub locked: bool,
+    /// Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+    #[arg(short = 'Z', value_name = "FLAG")]
+    pub unstable_flags: Vec<String>,
+    /// Arguments for mpiexec
+    #[arg(last = true, allow_hyphen_values = true)]
+    pub args: Vec<String>,
+}