docs(core): improve `target` documentation, cleanup logic, closes #4161 (#4173)

core/tauri/src/app.rs

@@ -1196,10 +1196,7 @@ impl<R: Runtime> Builder<R> {
 
   /// Sets the current platform's target name for the updater.
   ///
-  /// By default Tauri looks for a target in the format "{target}-{arch}",
-  /// where *target* is one of `darwin`, `linux` and `windows`
-  /// and *arch* is one of `i686`, `x86_64`, `aarch64` and `armv7`
-  /// based on the running platform. You can change the target name with this function.
+  /// See [`UpdateBuilder::target`](crate::updater::UpdateBuilder#method.target) for more information.
   ///
   /// # Examples
   ///

core/tauri/src/updater/core.rs

@@ -327,16 +327,14 @@ impl<R: Runtime> UpdateBuilder<R> {
     // If no executable path provided, we use current_exe from tauri_utils
     let executable_path = self.executable_path.unwrap_or(current_exe()?);
 
-    let has_custom_target = self.target.is_some();
-    let target = self
-      .target
-      .or_else(|| get_updater_target().map(Into::into))
-      .ok_or(Error::UnsupportedOs)?;
     let arch = get_updater_arch().ok_or(Error::UnsupportedArch)?;
-    let json_target = if has_custom_target {
-      target.clone()
+    // `target` is the `{{target}}` variable we replace in the endpoint
+    // `json_target` is the value we search if the updater server returns a JSON with the `platforms` object
+    let (target, json_target) = if let Some(target) = self.target {
+      (target.clone(), target)
     } else {
-      format!("{}-{}", target, arch)
+      let target = get_updater_target().ok_or(Error::UnsupportedOs)?;
+      (target.to_string(), format!("{}-{}", target, arch))
     };
 
     // Get the extract_path from the provided executable_path

core/tauri/src/updater/mod.rs

@@ -526,7 +526,85 @@ impl<R: Runtime> UpdateBuilder<R> {
     self
   }
 
-  /// Set the target name. Represents the string that is looked up on the updater API or response JSON.
+  /// Sets the current platform's target name for the updater.
+  ///
+  /// The target is injected in the endpoint URL by replacing `{{target}}`.
+  /// Note that this does not affect the `{{arch}}` variable.
+  ///
+  /// If the updater response JSON includes the `platforms` field,
+  /// that object must contain a value for the target key.
+  ///
+  /// By default Tauri uses `$OS_NAME` as the replacement for `{{target}}`
+  /// and `$OS_NAME-$ARCH` as the key in the `platforms` object,
+  /// where `$OS_NAME` is the current operating system name "linux", "windows" or "darwin")
+  /// and `$ARCH` is one of the supported architectures ("i686", "x86_64", "armv7" or "aarch64").
+  ///
+  /// See [`Builder::updater_target`](crate::Builder#method.updater_target) for a way to set the target globally.
+  ///
+  /// # Examples
+  ///
+  /// ## Use a macOS Universal binary target name
+  ///
+  /// In this example, we set the updater target only on macOS.
+  /// On other platforms, we set the default target.
+  /// Note that `{{target}}` will be replaced with `darwin-universal`,
+  /// but `{{arch}}` is still the running platform's architecture.
+  ///
+  /// ```no_run
+  /// tauri::Builder::default()
+  ///   .setup(|app| {
+  ///     let handle = app.handle();
+  ///     tauri::async_runtime::spawn(async move {
+  ///       let builder = tauri::updater::builder(handle).target(if cfg!(target_os = "macos") {
+  ///         "darwin-universal".to_string()
+  ///       } else {
+  ///         tauri::updater::target().unwrap()
+  ///       });
+  ///       match builder.check().await {
+  ///         Ok(update) => {}
+  ///         Err(error) => {}
+  ///       }
+  ///     });
+  ///     Ok(())
+  ///   });
+  /// ```
+  ///
+  /// ## Append debug information to the target
+  ///
+  /// This allows you to provide updates for both debug and release applications.
+  ///
+  /// ```no_run
+  /// tauri::Builder::default()
+  ///   .setup(|app| {
+  ///     let handle = app.handle();
+  ///     tauri::async_runtime::spawn(async move {
+  ///       let kind = if cfg!(debug_assertions) { "debug" } else { "release" };
+  ///       let builder = tauri::updater::builder(handle).target(format!("{}-{}", tauri::updater::target().unwrap(), kind));
+  ///       match builder.check().await {
+  ///         Ok(update) => {}
+  ///         Err(error) => {}
+  ///       }
+  ///     });
+  ///     Ok(())
+  ///   });
+  /// ```
+  ///
+  /// ## Use the platform's target triple
+  ///
+  /// ```no_run
+  /// tauri::Builder::default()
+  ///   .setup(|app| {
+  ///     let handle = app.handle();
+  ///     tauri::async_runtime::spawn(async move {
+  ///       let builder = tauri::updater::builder(handle).target(tauri::utils::platform::target_triple().unwrap());
+  ///       match builder.check().await {
+  ///         Ok(update) => {}
+  ///         Err(error) => {}
+  ///       }
+  ///     });
+  ///     Ok(())
+  ///   });
+  /// ```
   pub fn target(mut self, target: impl Into<String>) -> Self {
     self.inner = self.inner.target(target);
     self