Merge pull request #21 from tombh/tombh/full-usage-in-readme

Hidden command to dump usage for README

Author: schell

README.md

@@ -3,7 +3,7 @@ Command line tool for building Rust shaders using rust-gpu.
 
 ## Getting Started
 
-### installation
+### Installation
 To install the tool ensure you have `rustup`. Then run: 
 
 ```
@@ -32,3 +32,133 @@ git clone https://github.com/rust-GPU/shader-crate-template
 cd shader-crate-template
 cargo gpu build
 ```
+
+## Usage
+
+```
+Commands:
+  install  Install rust-gpu compiler artifacts
+  build    Compile a shader crate to SPIR-V
+  toml     Compile a shader crate according to the `cargo gpu build` parameters found in the given toml file
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help
+          Print help
+
+  -V, --version
+          Print version
+
+
+* Install
+
+Install rust-gpu compiler artifacts
+
+Usage: cargo-gpu install [OPTIONS]
+
+Options:
+      --spirv-builder <SPIRV_BUILDER>
+          spirv-builder dependency, written just like in a Cargo.toml file
+
+          [default: "{ git = \"https://github.com/Rust-GPU/rust-gpu.git\" }"]
+
+      --rust-toolchain <RUST_TOOLCHAIN>
+          Rust toolchain channel to use to build `spirv-builder`.
+
+          This must match the `spirv_builder` argument.
+
+          [default: nightly-2024-04-24]
+
+      --force-spirv-cli-rebuild
+          Force `spirv-builder-cli` and `rustc_codegen_spirv` to be rebuilt
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+
+* Build
+
+Compile a shader crate to SPIR-V
+
+Usage: cargo-gpu build [OPTIONS]
+
+Options:
+      --spirv-builder <SPIRV_BUILDER>
+          spirv-builder dependency, written just like in a Cargo.toml file
+
+          [default: "{ git = \"https://github.com/Rust-GPU/rust-gpu.git\" }"]
+
+      --rust-toolchain <RUST_TOOLCHAIN>
+          Rust toolchain channel to use to build `spirv-builder`.
+
+          This must match the `spirv_builder` argument.
+
+          [default: nightly-2024-04-24]
+
+      --force-spirv-cli-rebuild
+          Force `spirv-builder-cli` and `rustc_codegen_spirv` to be rebuilt
+
+      --shader-crate <SHADER_CRATE>
+          Directory containing the shader crate to compile
+
+          [default: ./]
+
+      --shader-target <SHADER_TARGET>
+          Shader target
+
+          [default: spirv-unknown-vulkan1.2]
+
+      --no-default-features
+          Set cargo default-features
+
+      --features <FEATURES>
+          Set cargo features
+
+  -o, --output-dir <OUTPUT_DIR>
+          Path to the output directory for the compiled shaders
+
+          [default: ./]
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+
+* Toml
+
+Compile a shader crate according to the `cargo gpu build` parameters found in the given toml file
+
+Usage: cargo-gpu toml [PATH]
+
+Arguments:
+  [PATH]
+          Path to a workspace or package Cargo.toml file.
+
+          Must include a [[workspace | package].metadata.rust-gpu.build] section where
+          arguments to `cargo gpu build` are listed.
+
+          Path arguments like `output-dir` and `shader-manifest` must be relative to
+          the location of the Cargo.toml file.
+
+          Example:
+
+          ```toml
+              [package.metadata.rust-gpu.build.spirv-builder]
+              git = "https://github.com/Rust-GPU/rust-gpu.git"
+              rev = "0da80f8"
+
+              [package.metadata.rust-gpu.build]
+              output-dir = "shaders"
+              shader-manifest = "shaders/manifest.json"
+          ```
+
+          Calling `cargo gpu toml {path/to/Cargo.toml}` with a Cargo.toml that
+          contains the example above would compile the crate and place the compiled
+          `.spv` files and manifest in a directory "shaders".
+
+          [default: ./Cargo.toml]
+
+Options:
+  -h, --help
+          Print help (see a summary with '-h')
+
+```

crates/cargo-gpu/src/main.rs

@@ -641,6 +641,7 @@ impl Toml {
         log::debug!("build parameters: {parameters:#?}");
         if let Cli {
             command: Command::Build(mut build),
+            ..
         } = Cli::parse_from(parameters)
         {
             log::debug!("build: {build:?}");
@@ -663,6 +664,12 @@ enum Command {
     /// Compile a shader crate according to the `cargo gpu build` parameters
     /// found in the given toml file.
     Toml(Toml),
+
+    /// A hidden command that can be used to recursively print out all the subcommand help messages:
+    ///   `cargo gpu dump-usage`
+    /// Useful for updating the README.
+    #[clap(hide(true))]
+    DumpUsage,
 }
 
 #[derive(Parser)]
@@ -702,6 +709,40 @@ fn main() {
         }
         Command::Build(mut build) => build.run(),
         Command::Toml(toml) => toml.run(),
+        Command::DumpUsage => dump_full_usage_for_readme(),
+    }
+}
+
+fn dump_full_usage_for_readme() {
+    use clap::CommandFactory;
+    let mut command = Cli::command();
+
+    let mut buffer: Vec<u8> = Default::default();
+    command.build();
+
+    write_help(&mut buffer, &mut command, 0);
+    let buffer = String::from_utf8(buffer).unwrap();
+    println!("{}", buffer);
+}
+
+fn write_help(buffer: &mut impl std::io::Write, cmd: &mut clap::Command, depth: usize) {
+    if cmd.get_name() == "help" {
+        return;
+    }
+
+    let mut command = cmd.get_name().to_string();
+    let _ = writeln!(
+        buffer,
+        "\n* {}{}",
+        command.remove(0).to_uppercase(),
+        command
+    );
+    let _ = writeln!(buffer);
+    let _ = cmd.write_long_help(buffer);
+
+    for sub in cmd.get_subcommands_mut() {
+        let _ = writeln!(buffer);
+        write_help(buffer, sub, depth + 1);
     }
 }
 
@@ -723,6 +764,7 @@ mod test {
         ];
         if let Cli {
             command: Command::Build(build),
+            ..
         } = Cli::parse_from(args)
         {
             assert_eq!(shader_crate, build.shader_crate);