Make TOML config keys kebab-case, and add docs (bytecodealliance#10132)

* Update cli book docs for toml option

* Make TOML keys use kebab-case in order to match cli names

Author: ludfjig

crates/cli-flags/src/lib.rs

@@ -43,7 +43,7 @@ fn init_file_per_thread_logger(prefix: &'static str) {
 
 wasmtime_option_group! {
     #[derive(PartialEq, Clone, Deserialize)]
-    #[serde(deny_unknown_fields)]
+    #[serde(rename_all = "kebab-case", deny_unknown_fields)]
     pub struct OptimizeOptions {
         /// Optimization level of generated code (0-2, s; default: 2)
         #[serde(default)]
@@ -202,7 +202,7 @@ wasmtime_option_group! {
 
 wasmtime_option_group! {
     #[derive(PartialEq, Clone, Deserialize)]
-    #[serde(deny_unknown_fields)]
+    #[serde(rename_all = "kebab-case", deny_unknown_fields)]
     pub struct CodegenOptions {
         /// Either `cranelift` or `winch`.
         ///
@@ -251,7 +251,7 @@ wasmtime_option_group! {
 
 wasmtime_option_group! {
     #[derive(PartialEq, Clone, Deserialize)]
-    #[serde(deny_unknown_fields)]
+    #[serde(rename_all = "kebab-case", deny_unknown_fields)]
     pub struct DebugOptions {
         /// Enable generation of DWARF debug information in compiled code.
         pub debug_info: Option<bool>,
@@ -272,7 +272,7 @@ wasmtime_option_group! {
 
 wasmtime_option_group! {
     #[derive(PartialEq, Clone, Deserialize)]
-    #[serde(deny_unknown_fields)]
+    #[serde(rename_all = "kebab-case", deny_unknown_fields)]
     pub struct WasmOptions {
         /// Enable canonicalization of all NaN values.
         pub nan_canonicalization: Option<bool>,
@@ -387,7 +387,7 @@ wasmtime_option_group! {
 
 wasmtime_option_group! {
     #[derive(PartialEq, Clone, Deserialize)]
-    #[serde(deny_unknown_fields)]
+    #[serde(rename_all = "kebab-case", deny_unknown_fields)]
     pub struct WasiOptions {
         /// Enable support for WASI CLI APIs, including filesystems, sockets, clocks, and random.
         pub cli: Option<bool>,
@@ -1047,7 +1047,7 @@ mod tests {
             let toml = format!(
                 r#"
                     [optimize]
-                    opt_level = {opt_value}
+                    opt-level = {opt_value}
                 "#,
             );
             let parsed_opt_level = toml::from_str::<CommonOptions>(&toml)
@@ -1071,7 +1071,7 @@ mod tests {
             let toml = format!(
                 r#"
                     [optimize]
-                    regalloc_algorithm = {regalloc_value}
+                    regalloc-algorithm = {regalloc_value}
                 "#,
             );
             let parsed_regalloc_algorithm = toml::from_str::<CommonOptions>(&toml)

docs/cli-options.md

@@ -126,3 +126,56 @@ display what Cranelift settings are inferred for the host:
 ```sh
 $ wasmtime settings
 ```
+
+# Additional options
+Many of the above subcommands also take additional options. For example,
+- run 
+- serve
+- compile
+- explore
+- wast
+
+are all subcommands which can take additional CLI options of the format 
+
+```sh
+Options:
+  -O, --optimize <KEY[=VAL[,..]]>
+          Optimization and tuning related options for wasm performance, `-O help` to see all
+
+  -C, --codegen <KEY[=VAL[,..]]>
+          Codegen-related configuration options, `-C help` to see all
+
+  -D, --debug <KEY[=VAL[,..]]>
+          Debug-related configuration options, `-D help` to see all
+
+  -W, --wasm <KEY[=VAL[,..]]>
+          Options for configuring semantic execution of WebAssembly, `-W help` to see all
+
+  -S, --wasi <KEY[=VAL[,..]]>
+          Options for configuring WASI and its proposals, `-S help` to see all
+```
+
+For example, adding `--optimize opt-level=0` to a `wasmtime compile` subcommand
+will turn off most optimizations for the generated code.
+
+## CLI options using TOML file 
+Most key-value options that can be provided using the `--optimize`, `--codegen`,
+`--debug`, `--wasm`, and `--wasi` flags can also be provided using a TOML
+file using the `--config <FILE>` cli flag, by putting the key-value inside a TOML
+table with the same name. 
+
+For example, with a TOML file like this
+```toml
+[optimize]
+opt-level = 0
+```
+the command
+```sh
+$ wasmtime compile --config config.toml
+``` 
+would be the same as 
+```sh
+$ wasmtime compile --optimize opt-level=0
+```
+assuming the TOML file is called `config.toml`. Of course you can put as many
+key-value pairs as you want in the TOML file.

tests/all/cli_tests.rs

@@ -2161,18 +2161,18 @@ fn config_cli_flag() -> Result<()> {
     cfg.write_all(
         br#"
         [optimize]
-        opt_level = 2
-        regalloc_algorithm = "single-pass"
-        signals_based_traps = false
+        opt-level = 2
+        regalloc-algorithm = "single-pass"
+        signals-based-traps = false
 
         [codegen]
         collector = "null"
 
         [debug]
-        debug_info = true
+        debug-info = true
 
         [wasm]
-        max_wasm_stack = 65536
+        max-wasm-stack = 65536
 
         [wasi]
         cli = true
@@ -2213,7 +2213,7 @@ fn config_cli_flag() -> Result<()> {
     cfg.write_all(
         br#"
         [optimize]
-        this_key_does_not_exist = true
+        this-key-does-not-exist = true
         "#,
     )?;
     let output = run_wasmtime(&[
@@ -2227,7 +2227,7 @@ fn config_cli_flag() -> Result<()> {
             .as_ref()
             .unwrap_err()
             .to_string()
-            .contains("unknown field `this_key_does_not_exist`"),
+            .contains("unknown field `this-key-does-not-exist`"),
         "'{output:?}' did not contain expected error message"
     );