Expand --help output for component new command

src/bin/wasm-tools/component.rs

@@ -75,6 +75,45 @@ fn parse_import_name(s: &str) -> Result<(String, String)> {
 /// used during compilation of the core wasm module and will produce a component
 /// with all of this type information resolved.
 #[derive(Parser)]
+#[clap(after_help = "\
+Examples:
+
+    # Supposing foo.wasm contains a binary core module,
+    # create a component using the adapter in the
+    # file `wasi_snapshot_preview1.reactor.wasm`, and save the binary
+    # component to the file foo.component.wasm.
+    $ wasm-tools component new foo.wasm --adapt wasi_snapshot_preview1.reactor.wasm \
+        -o foo.component.wasm
+
+    # Supporting foo.wasm contains a binary core module,
+    # create a component using the adapter in the
+    # file some_adapter.wasm, which must implement the import module
+    # \"wasi_snapshot_preview1\", and save the binary component to the file
+    # foo.component.wasm.
+    $ wasm-tools component new foo.wasm --adapt wasi_snapshot_preview1=some_adapter.wasm \
+        -o foo.component.wasm
+
+    # In the output component, replace any imports of \"wasi:io/error@0.2.0\" with
+    # an import of \"unlocked-dep=<wasi:io/error>\". This has the effect of changing
+    # the dependency on `wasi:io/error` from an exact version to one of a set of
+    # possible versions of this dependency.
+    # (For more on locked vs. unlocked dependencies, see
+    # https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#import-and-export-definitions)
+    # Also use the adapter contained in the file `wasm_snapshot_preview1.wasm`
+    # in the current directory, and save the output to the file foo.component.wasm.
+    $ wasm-tools component new foo.wasm --import-name \"wasi:io/error@0.2.0=unlocked-dep=<wasi:io/error>\" \
+        --adapt wasi_snapshot_preview1.wasm -o foo.component.wasm
+
+    # Create a component and print it to stdout in in text format, skipping validation of
+    # the output component.
+    $ wasm-tools component new foo.wasm -t --skip-validation
+
+    # Create a component, using memory.grow to reallocate memory.
+    # This can be useful if `cabi_realloc` cannot be called before the host runtime
+    # is initialized.
+    $ wasm-tools component new foo.wasm --realloc-via-memory-grow \
+        --adapt wasi_snapshot_preview1.reactor.wasm -o foo.component.wasm
+")]
 pub struct NewOpts {
     #[clap(flatten)]
     adapters: wasm_tools::AdaptersArg,
@@ -113,7 +152,7 @@ pub struct NewOpts {
     /// semver ranges.
     ///
     /// This is enabled by default.
-    #[clap(long, value_name = "MERGE")]
+    #[clap(long, value_name = "<true|false>")]
     merge_imports_based_on_semver: Option<bool>,
 
     /// Reject usage of the "legacy" naming scheme of `wit-component` and

tests/cli/help-component-new-short.wat

@@ -0,0 +1 @@
+;; RUN: component new -h

tests/cli/help-component-new-short.wat.stdout

@@ -0,0 +1,83 @@
+WebAssembly component encoder from an input core wasm binary
+
+Usage: wasm-tools component new [OPTIONS] [INPUT]
+
+Arguments:
+  [INPUT]  Input file to process
+
+Options:
+      --adapt <[NAME=]MODULE>
+          The path to an adapter module to satisfy imports not otherwise bound
+          to WIT interfaces
+      --import-name <OLD=NEW>
+          Rename an instance import in the output component
+      --generate-dwarf <lines|full>
+          Optionally generate DWARF debugging information from WebAssembly text
+          files
+  -g
+          Shorthand for `--generate-dwarf full`
+  -o, --output <OUTPUT>
+          Where to place output
+  -v, --verbose...
+          Use verbose output (-v info, -vv debug, -vvv trace)
+      --color <COLOR>
+          Configuration over whether terminal colors are used in output
+          [default: auto]
+      --skip-validation
+          Skip validation of the output component
+  -t, --wat
+          Print the output in the WebAssembly text format instead of binary
+      --realloc-via-memory-grow
+          Use memory.grow to realloc memory and stack allocation
+      --merge-imports-based-on-semver <<true|false>>
+          Indicates whether imports into the final component are merged based on
+          semver ranges [possible values: true, false]
+      --reject-legacy-names
+          Reject usage of the "legacy" naming scheme of `wit-component` and
+          require the new naming scheme to be used
+  -h, --help
+          Print help (see more with '--help')
+
+Examples:
+
+    # Supposing foo.wasm contains a binary core module,
+    # create a component using the adapter in the
+    # file `wasi_snapshot_preview1.reactor.wasm`, and save the binary
+    # component to the file foo.component.wasm.
+    $ wasm-tools component new foo.wasm --adapt
+    wasi_snapshot_preview1.reactor.wasm -o foo.component.wasm
+
+    # Supporting foo.wasm contains a binary core module,
+    # create a component using the adapter in the
+    # file some_adapter.wasm, which must implement the import module
+    # "wasi_snapshot_preview1", and save the binary component to the file
+    # foo.component.wasm.
+    $ wasm-tools component new foo.wasm --adapt
+    wasi_snapshot_preview1=some_adapter.wasm -o foo.component.wasm
+
+    # In the output component, replace any imports of "wasi:io/error@0.2.0" with
+    # an import of "unlocked-dep=<wasi:io/error>". This has the effect of
+    changing
+    # the dependency on `wasi:io/error` from an exact version to one of a set of
+    # possible versions of this dependency.
+    # (For more on locked vs. unlocked dependencies, see
+    #
+    https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#import-and-export-definitions)
+    # Also use the adapter contained in the file `wasm_snapshot_preview1.wasm`
+    # in the current directory, and save the output to the file
+    foo.component.wasm.
+    $ wasm-tools component new foo.wasm --import-name
+    "wasi:io/error@0.2.0=unlocked-dep=<wasi:io/error>" --adapt
+    wasi_snapshot_preview1.wasm -o foo.component.wasm
+
+    # Create a component and print it to stdout in in text format, skipping
+    validation of
+    # the output component.
+    $ wasm-tools component new foo.wasm -t --skip-validation
+
+    # Create a component, using memory.grow to reallocate memory.
+    # This can be useful if `cabi_realloc` cannot be called before the host
+    runtime
+    # is initialized.
+    $ wasm-tools component new foo.wasm --realloc-via-memory-grow --adapt
+    wasi_snapshot_preview1.reactor.wasm -o foo.component.wasm

tests/cli/help-component-new.wat

@@ -0,0 +1 @@
+;; RUN: component new --help

tests/cli/help-component-new.wat.stdout

@@ -0,0 +1,153 @@
+WebAssembly component encoder from an input core wasm binary.
+
+This subcommand will create a new component `*.wasm` file from an input core
+wasm binary. The input core wasm binary must have metadata embedded within it
+about the component-types used during its compilation. This is done
+automatically for `wit-bindgen`-based projects, for example, and can be manually
+done through the `wasm-tools component embed` subcommand.
+
+This command will perform translation by collecting all type information used
+during compilation of the core wasm module and will produce a component with all
+of this type information resolved.
+
+Usage: wasm-tools component new [OPTIONS] [INPUT]
+
+Arguments:
+  [INPUT]
+          Input file to process.
+
+          If not provided or if this is `-` then stdin is read entirely and
+          processed. Note that for most subcommands this input can either be a
+          binary `*.wasm` file or a textual format `*.wat` file.
+
+Options:
+      --adapt <[NAME=]MODULE>
+          The path to an adapter module to satisfy imports not otherwise bound
+          to WIT interfaces.
+
+          An adapter module can be used to translate the
+          `wasi_snapshot_preview1` ABI, for example, to one that uses the
+          component model. The first `[NAME=]` specified in the argument is
+          inferred from the name of file specified by `MODULE` if not present
+          and is the name of the import module that's being implemented (e.g.
+          `wasi_snapshot_preview1.wasm`).
+
+          The second part of this argument is the path to the adapter module.
+
+      --import-name <OLD=NEW>
+          Rename an instance import in the output component.
+
+          This may be used to rename instance imports in the final component.
+
+          For example, `--import-name "a:b/c=unlocked-dep=<d:e/f>"` will rename
+          the instance import `a:b/c` such that it becomes an `unlocked-dep`
+          name.
+
+          If the old import name is not found, it is ignored.
+
+      --generate-dwarf <lines|full>
+          Optionally generate DWARF debugging information from WebAssembly text
+          files.
+
+          When the input to this command is a WebAssembly text file, such as
+          `*.wat`, then this option will instruct the text parser to insert
+          DWARF debugging information to map binary locations back to the
+          original source locations in the input `*.wat` file. This option has
+          no effect if the `INPUT` argument is already a WebAssembly binary or
+          if the text format uses `(module binary ...)`.
+
+  -g
+          Shorthand for `--generate-dwarf full`
+
+  -o, --output <OUTPUT>
+          Where to place output.
+
+          Required when printing WebAssembly binary output.
+
+          If not provided, then stdout is used.
+
+  -v, --verbose...
+          Use verbose output (-v info, -vv debug, -vvv trace)
+
+      --color <COLOR>
+          Configuration over whether terminal colors are used in output.
+
+          Supports one of `auto|never|always|always-ansi`. The default is to
+          detect what to do based on the terminal environment, for example by
+          using `isatty`.
+
+          [default: auto]
+
+      --skip-validation
+          Skip validation of the output component
+
+  -t, --wat
+          Print the output in the WebAssembly text format instead of binary
+
+      --realloc-via-memory-grow
+          Use memory.grow to realloc memory and stack allocation
+
+      --merge-imports-based-on-semver <<true|false>>
+          Indicates whether imports into the final component are merged based on
+          semver ranges.
+
+          This is enabled by default.
+
+          [possible values: true, false]
+
+      --reject-legacy-names
+          Reject usage of the "legacy" naming scheme of `wit-component` and
+          require the new naming scheme to be used.
+
+          This flag can be used to ignore core module imports/exports that don't
+          conform to WebAssembly/component-model#378. This turns off
+          compatibility `wit-component`'s historical naming scheme. This is
+          intended to be used to test if a tool is compatible with a
+          hypothetical removal of the old scheme in the future.
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Examples:
+
+    # Supposing foo.wasm contains a binary core module,
+    # create a component using the adapter in the
+    # file `wasi_snapshot_preview1.reactor.wasm`, and save the binary
+    # component to the file foo.component.wasm.
+    $ wasm-tools component new foo.wasm --adapt
+    wasi_snapshot_preview1.reactor.wasm -o foo.component.wasm
+
+    # Supporting foo.wasm contains a binary core module,
+    # create a component using the adapter in the
+    # file some_adapter.wasm, which must implement the import module
+    # "wasi_snapshot_preview1", and save the binary component to the file
+    # foo.component.wasm.
+    $ wasm-tools component new foo.wasm --adapt
+    wasi_snapshot_preview1=some_adapter.wasm -o foo.component.wasm
+
+    # In the output component, replace any imports of "wasi:io/error@0.2.0" with
+    # an import of "unlocked-dep=<wasi:io/error>". This has the effect of
+    changing
+    # the dependency on `wasi:io/error` from an exact version to one of a set of
+    # possible versions of this dependency.
+    # (For more on locked vs. unlocked dependencies, see
+    #
+    https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#import-and-export-definitions)
+    # Also use the adapter contained in the file `wasm_snapshot_preview1.wasm`
+    # in the current directory, and save the output to the file
+    foo.component.wasm.
+    $ wasm-tools component new foo.wasm --import-name
+    "wasi:io/error@0.2.0=unlocked-dep=<wasi:io/error>" --adapt
+    wasi_snapshot_preview1.wasm -o foo.component.wasm
+
+    # Create a component and print it to stdout in in text format, skipping
+    validation of
+    # the output component.
+    $ wasm-tools component new foo.wasm -t --skip-validation
+
+    # Create a component, using memory.grow to reallocate memory.
+    # This can be useful if `cabi_realloc` cannot be called before the host
+    runtime
+    # is initialized.
+    $ wasm-tools component new foo.wasm --realloc-via-memory-grow --adapt
+    wasi_snapshot_preview1.reactor.wasm -o foo.component.wasm