feat(config): adjust schema for documentation website, closes #4139 (#4142)

Co-authored-by: Lorenzo Lewis <lorenzo_lewis@icloud.com>

Author: lucasfernog

.changes/bundler-tsp-bool.md

@@ -0,0 +1,5 @@
+---
+"tauri-bundler": patch
+---
+
+Change `tsp` value from `Option<bool>` to `bool`.

core/tauri-utils/src/config.rs

@@ -42,7 +42,9 @@ pub use self::parse::parse;
 pub enum WindowUrl {
   /// An external URL.
   External(Url),
-  /// An app URL.
+  /// The path portion of an app URL.
+  /// For instance, to load `tauri://localhost/users/john`,
+  /// you can simply provide `users/john` in this configuration.
   App(PathBuf),
 }
 
@@ -251,7 +253,8 @@ pub struct WindowsConfig {
   pub timestamp_url: Option<String>,
   /// Whether to use Time-Stamp Protocol (TSP, a.k.a. RFC 3161) for the timestamp server. Your code signing provider may
   /// use a TSP timestamp server, like e.g. SSL.com does. If so, enable TSP by setting to true.
-  pub tsp: Option<bool>,
+  #[serde(default)]
+  pub tsp: bool,
   /// Path to the webview fixed runtime to use.
   ///
   /// The fixed version can be downloaded [on the official website](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section).
@@ -274,7 +277,7 @@ impl Default for WindowsConfig {
       digest_algorithm: None,
       certificate_thumbprint: None,
       timestamp_url: None,
-      tsp: None,
+      tsp: false,
       webview_fixed_runtime_path: None,
       allow_downgrades: default_allow_downgrades(),
       wix: None,
@@ -364,19 +367,22 @@ pub struct CliArg {
   /// - Using a space such as -o value or --option value
   /// - Using an equals and no space such as -o=value or --option=value
   /// - Use a short and no space such as -ovalue
-  pub takes_value: Option<bool>,
+  #[serde(default)]
+  pub takes_value: bool,
   /// Specifies that the argument may have an unknown number of multiple values. Without any other settings, this argument may appear only once.
   ///
   /// For example, --opt val1 val2 is allowed, but --opt val1 val2 --opt val3 is not.
   ///
   /// NOTE: Setting this requires `takes_value` to be set to true.
-  pub multiple: Option<bool>,
+  #[serde(default)]
+  pub multiple: bool,
   /// Specifies that the argument may appear more than once.
   /// For flags, this results in the number of occurrences of the flag being recorded. For example -ddd or -d -d -d would count as three occurrences.
   /// For options or arguments that take a value, this does not affect how many values they can accept. (i.e. only one at a time is allowed)
   ///
   /// For example, --opt val1 --opt val2 is allowed, but --opt val1 val2 is not.
-  pub multiple_occurrences: Option<bool>,
+  #[serde(default)]
+  pub multiple_occurrences: bool,
   /// Specifies how many values are required to satisfy this argument. For example, if you had a
   /// `-f <file>` argument where you wanted exactly 3 'files' you would set
   /// `number_of_values = 3`, and this argument wouldn't be satisfied unless the user provided
@@ -392,18 +398,19 @@ pub struct CliArg {
   /// At runtime, the CLI verifies that only one of the specified values was used, or fails with an error message.
   pub possible_values: Option<Vec<String>>,
   /// Specifies the minimum number of values for this argument.
-  /// For example, if you had a -f <file> argument where you wanted at least 2 'files',
+  /// For example, if you had a -f `<file>` argument where you wanted at least 2 'files',
   /// you would set `minValues: 2`, and this argument would be satisfied if the user provided, 2 or more values.
   pub min_values: Option<usize>,
   /// Specifies the maximum number of values are for this argument.
-  /// For example, if you had a -f <file> argument where you wanted up to 3 'files',
+  /// For example, if you had a -f `<file>` argument where you wanted up to 3 'files',
   /// you would set .max_values(3), and this argument would be satisfied if the user provided, 1, 2, or 3 values.
   pub max_values: Option<usize>,
   /// Sets whether or not the argument is required by default.
   ///
   /// - Required by default means it is required, when no other conflicting rules have been evaluated
   /// - Conflicting rules take precedence over being required.
-  pub required: Option<bool>,
+  #[serde(default)]
+  pub required: bool,
   /// Sets an arg that override this arg's required setting
   /// i.e. this arg will be required unless this other argument is present.
   pub required_unless_present: Option<String>,
@@ -438,6 +445,7 @@ pub struct CliArg {
   /// The index refers to position according to other positional argument.
   /// It does not define position in the argument list as a whole. When utilized with multiple=true,
   /// only the last positional argument may be defined as multiple (i.e. the one with the highest index).
+  #[cfg_attr(feature = "schema", validate(range(min = 1)))]
   pub index: Option<usize>,
 }
 
@@ -792,7 +800,7 @@ impl Default for DisabledCspModificationKind {
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct SecurityConfig {
   /// The Content Security Policy that will be injected on all HTML files on the built application.
-  /// If [`dev_csp`](SecurityConfig.dev_csp) is not specified, this value is also injected on dev.
+  /// If [`dev_csp`](#SecurityConfig.devCsp) is not specified, this value is also injected on dev.
   ///
   /// This is a really important part of the configuration since it helps you ensure your WebView is secured.
   /// See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
@@ -1272,7 +1280,7 @@ pub struct ShellAllowlistConfig {
   pub execute: bool,
   /// Enable sidecar execution, allowing the JavaScript layer to spawn a sidecar command,
   /// an executable that is shipped with the application.
-  /// For more information see <https://tauri.studio/docs/guides/bundler/sidecar/>.
+  /// For more information see <https://tauri.studio/v1/guides/building/sidecar>.
   #[serde(default)]
   pub sidecar: bool,
   /// Open URL with the user's default application.
@@ -1975,7 +1983,6 @@ pub struct UpdaterConfig {
   /// - {{arch}}: The architecture of the machine (one of `x86_64`, `i686`, `aarch64` or `armv7`).
   ///
   /// # Examples
-  ///
   /// - "https://my.cdn.com/latest.json": a raw JSON endpoint that returns the latest version and download links for each platform.
   /// - "https://updates.app.dev/{{target}}?version={{current_version}}&arch={{arch}}": a dedicated API with positional and query string arguments.
   #[allow(rustdoc::bare_urls)]
@@ -2057,7 +2064,7 @@ fn default_dialog() -> bool {
   true
 }
 
-/// The `dev_path` and `dist_dir` options.
+/// Defines the URL or assets to embed in the application.
 #[derive(Debug, PartialEq, Clone, Deserialize, Serialize)]
 #[cfg_attr(feature = "schema", derive(JsonSchema))]
 #[serde(untagged, deny_unknown_fields)]
@@ -2086,10 +2093,26 @@ impl std::fmt::Display for AppUrl {
 pub struct BuildConfig {
   /// The binary used to build and run the application.
   pub runner: Option<String>,
-  /// The path or URL to use on development.
+  /// The path to the application assets or URL to load in development.
+  ///
+  /// This is usually an URL to a dev server, which serves your application assets
+  /// with live reloading. Most modern JavaScript bundlers provides a way to start a dev server by default.
+  ///
+  /// See [vite](https://vitejs.dev/guide/), [Webpack DevServer](https://webpack.js.org/configuration/dev-server/) and [sirv](https://github.com/lukeed/sirv)
+  /// for examples on how to set up a dev server.
   #[serde(default = "default_dev_path")]
   pub dev_path: AppUrl,
-  /// The path to the app's dist dir. This path must contain your index.html file.
+  /// The path to the application assets or URL to load in production.
+  ///
+  /// When a path relative to the configuration file is provided,
+  /// it is read recursively and all files are embedded in the application binary.
+  /// Tauri then looks for an `index.html` file unless you provide a custom window URL.
+  ///
+  /// You can also provide a list of paths to be embedded, which allows granular control over what files are added to the binary.
+  /// In this case, all files are added to the root and you must reference it that way in your HTML files.
+  ///
+  /// When an URL is provided, the application won't have bundled assets
+  /// and the application will load that URL by default.
   #[serde(default = "default_dist_dir")]
   pub dist_dir: AppUrl,
   /// A shell command to run before `tauri dev` kicks in.
@@ -2210,6 +2233,51 @@ impl PackageConfig {
 }
 
 /// The config type mapped to `tauri.conf.json`.
+/// The tauri.conf.json is a file generated by the
+/// [`tauri init`](https://tauri.studio/v1/api/cli#init) command that lives in
+/// your Tauri application source directory (src-tauri). Once generated, you may
+/// modify it at will to customize your Tauri application.
+/// 
+/// In addition to the JSON defined on the `tauri.conf.json` file, Tauri can
+/// read a platform-specific configuration from `tauri.linux.conf.json`,
+/// `tauri.windows.conf.json`, and `tauri.macos.conf.json` and merges it with
+/// the main `tauri.conf.json` configuration.
+/// 
+/// ```json title="Example tauri.config.json file"
+/// {
+///   "build": {
+///     "beforeBuildCommand": "",
+///     "beforeDevCommand": "",
+///     "devPath": "../dist",
+///     "distDir": "../dist"
+///   },
+///   "package": {
+///     "productName": "tauri-app",
+///     "version": "0.1.0"
+///   },
+///   "tauri": {
+///     "allowlist": {
+///       "all": true
+///     },
+///     // The below `bundle` object has been edited for brevity
+///     "bundle": {...},
+///     "security": {
+///       "csp": null
+///     },
+///     "updater": {
+///       "active": false
+///     },
+///     "windows": [
+///       {
+///         "fullscreen": false,
+///         "height": 600,
+///         "resizable": true,
+///         "title": "Tauri App",
+///         "width": 800
+///       }
+///     ]
+///   }
+/// }
 #[skip_serializing_none]
 #[derive(Debug, Default, PartialEq, Clone, Deserialize, Serialize)]
 #[cfg_attr(feature = "schema", derive(JsonSchema))]
@@ -2503,14 +2571,14 @@ mod build {
       let name = str_lit(&self.name);
       let description = opt_str_lit(self.description.as_ref());
       let long_description = opt_str_lit(self.long_description.as_ref());
-      let takes_value = opt_lit(self.takes_value.as_ref());
-      let multiple = opt_lit(self.multiple.as_ref());
-      let multiple_occurrences = opt_lit(self.multiple_occurrences.as_ref());
+      let takes_value = self.takes_value;
+      let multiple = self.multiple;
+      let multiple_occurrences = self.multiple_occurrences;
       let number_of_values = opt_lit(self.number_of_values.as_ref());
       let possible_values = opt_vec_str_lit(self.possible_values.as_ref());
       let min_values = opt_lit(self.min_values.as_ref());
       let max_values = opt_lit(self.max_values.as_ref());
-      let required = opt_lit(self.required.as_ref());
+      let required = self.required;
       let required_unless_present = opt_str_lit(self.required_unless_present.as_ref());
       let required_unless_present_all = opt_vec_str_lit(self.required_unless_present_all.as_ref());
       let required_unless_present_any = opt_vec_str_lit(self.required_unless_present_any.as_ref());

core/tauri/src/api/cli.rs

@@ -148,9 +148,9 @@ fn map_matches(config: &CliConfig, matches: &ArgMatches, cli_matches: &mut Match
   if let Some(args) = config.args() {
     for arg in args {
       let occurrences = matches.occurrences_of(arg.name.clone());
-      let value = if occurrences == 0 || !arg.takes_value.unwrap_or(false) {
+      let value = if occurrences == 0 || !arg.takes_value {
         Value::Bool(occurrences > 0)
-      } else if arg.multiple.unwrap_or(false) {
+      } else if arg.multiple {
         matches
           .values_of(arg.name.clone())
           .map(|v| {
@@ -230,16 +230,14 @@ fn get_arg<'a>(arg_name: &'a str, arg: &'a CliArg) -> Arg<'a> {
 
   clap_arg = bind_string_arg!(arg, clap_arg, description, help);
   clap_arg = bind_string_arg!(arg, clap_arg, long_description, long_help);
-  clap_arg = bind_value_arg!(arg, clap_arg, takes_value);
-  if let Some(value) = arg.multiple {
-    clap_arg = clap_arg.multiple_values(value);
-  }
-  clap_arg = bind_value_arg!(arg, clap_arg, multiple_occurrences);
+  clap_arg = clap_arg.takes_value(arg.takes_value);
+  clap_arg = clap_arg.multiple_values(arg.multiple);
+  clap_arg = clap_arg.multiple_occurrences(arg.multiple_occurrences);
   clap_arg = bind_value_arg!(arg, clap_arg, number_of_values);
   clap_arg = bind_string_slice_arg!(arg, clap_arg, possible_values);
   clap_arg = bind_value_arg!(arg, clap_arg, min_values);
   clap_arg = bind_value_arg!(arg, clap_arg, max_values);
-  clap_arg = bind_value_arg!(arg, clap_arg, required);
+  clap_arg = clap_arg.required(arg.required);
   clap_arg = bind_string_arg!(
     arg,
     clap_arg,

tooling/bundler/src/bundle/settings.rs

@@ -233,7 +233,7 @@ pub struct WindowsSettings {
   pub timestamp_url: Option<String>,
   /// Whether to use Time-Stamp Protocol (TSP, a.k.a. RFC 3161) for the timestamp server. Your code signing provider may
   /// use a TSP timestamp server, like e.g. SSL.com does. If so, enable TSP by setting to true.
-  pub tsp: Option<bool>,
+  pub tsp: bool,
   /// WiX configuration.
   pub wix: Option<WixSettings>,
   /// The path to the application icon. Defaults to `./icons/icon.ico`.
@@ -254,7 +254,7 @@ impl Default for WindowsSettings {
       digest_algorithm: None,
       certificate_thumbprint: None,
       timestamp_url: None,
-      tsp: None,
+      tsp: false,
       wix: None,
       icon_path: PathBuf::from("icons/icon.ico"),
       webview_fixed_runtime_path: None,

tooling/bundler/src/bundle/windows/sign.rs

@@ -19,7 +19,7 @@ pub struct SignParams {
   pub digest_algorithm: String,
   pub certificate_thumbprint: String,
   pub timestamp_url: Option<String>,
-  pub tsp: Option<bool>,
+  pub tsp: bool,
 }
 
 // sign code forked from https://github.com/forbjok/rust-codesign
@@ -107,7 +107,7 @@ pub fn sign<P: AsRef<Path>>(path: P, params: &SignParams) -> crate::Result<()> {
   cmd.args(&["/d", &params.product_name]);
 
   if let Some(ref timestamp_url) = params.timestamp_url {
-    if params.tsp == Some(true) {
+    if params.tsp {
       cmd.args(&["/tr", timestamp_url]);
       cmd.args(&["/td", &params.digest_algorithm]);
     } else {