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 ### Full Usage ``` -cargo-mpirun 0.1 -Andrew Gaspar -Run the main binary of the local package (src/main.rs) using mpiexec. - -USAGE: - cargo mpirun [OPTIONS] - -OPTIONS: - -n, --np Number of processes to run - -N, --npernode - 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 of the bin target to run - --example Name of the example target to run - -p, --package Package with the target to run - -j, --jobs - Number of parallel jobs, defaults to # of CPUs - - --release - Build artifacts in release mode, with optimizations - - --features ... - Space-separated list of features to also build - - --all-features Build all available features - --no-default-features Do not build the `default` feature - --target Build for the target triple - --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 Coloring [values: auto, always, never] - --message-format - 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 ... 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] [-- ...] + +Arguments: + [ARGS]... + Arguments for mpiexec + +Options: + -n, --np + Number of processes + + -N, --npernode + Number of processes per node on all allocated nodes + + --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 + Name of bin target to run + + --example + Name of example target to run + + -p, --package + Package with the target to run + + -j, --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 + 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 + Build for the target triple + + --target-dir + Directory for all generated artifacts + + --config + Override a configuration value + + --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 + 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 + 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 +```