feat(auto-start): introduce a builder (#2569)

* feat(auto-start): introduce a builder

* Update examples

* Fix missing end --- in change file

* Fix missing self.

* Update .changes/autostart-builder.md

Co-authored-by: Amr Bashir <[email protected]>

---------

Co-authored-by: Amr Bashir <[email protected]>

Author: Legend-Master

.changes/autostart-builder.md

@@ -0,0 +1,6 @@
+---
+autostart: minor
+autostart-js: minor
+---
+
+Add a `Builder` for more flexible settings

plugins/autostart/README.md

@@ -57,11 +57,9 @@ First you need to register the core plugin with Tauri:
 `src-tauri/src/lib.rs`
 
 ```rust
-use tauri_plugin_autostart::MacosLauncher;
-
 fn main() {
     tauri::Builder::default()
-        .plugin(tauri_plugin_autostart::init(MacosLauncher::LaunchAgent, Some(vec!["--flag1", "--flag2"]) /* arbitrary number of args to pass to your app */))
+        .plugin(tauri_plugin_autostart::Builder::new().args((["--flag1", "--flag2"])).build()))
         .run(tauri::generate_context!())
         .expect("error while running tauri application");
 }

plugins/autostart/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"

plugins/autostart/src/lib.rs

@@ -14,16 +14,17 @@ use auto_launch::{AutoLaunch, AutoLaunchBuilder};
 use serde::{ser::Serializer, Serialize};
 use tauri::{
     command,
-    plugin::{Builder, TauriPlugin},
+    plugin::{Builder as PluginBuilder, TauriPlugin},
     Manager, Runtime, State,
 };
 
 use std::env::current_exe;
 
 type Result<T> = std::result::Result<T, Error>;
 
-#[derive(Debug, Copy, Clone)]
+#[derive(Debug, Default, Copy, Clone)]
 pub enum MacosLauncher {
+    #[default]
     LaunchAgent,
     AppleScript,
 }
@@ -71,10 +72,12 @@ impl AutoLaunchManager {
 }
 
 pub trait ManagerExt<R: Runtime> {
+    /// TODO: Rename these to `autostart` or `auto_start` in v3
     fn autolaunch(&self) -> State<'_, AutoLaunchManager>;
 }
 
 impl<R: Runtime, T: Manager<R>> ManagerExt<R> for T {
+    /// TODO: Rename these to `autostart` or `auto_start` in v3
     fn autolaunch(&self) -> State<'_, AutoLaunchManager> {
         self.state::<AutoLaunchManager>()
     }
@@ -95,59 +98,132 @@ async fn is_enabled(manager: State<'_, AutoLaunchManager>) -> Result<bool> {
     manager.is_enabled()
 }
 
+#[derive(Default)]
+pub struct Builder {
+    #[cfg(target_os = "macos")]
+    macos_launcher: MacosLauncher,
+    args: Vec<String>,
+}
+
+impl Builder {
+    /// Create a new auto start builder with default settings
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Adds an argument to pass to your app on startup.
+    ///
+    /// ## Examples
+    ///
+    /// ```no_run
+    /// Builder::new()
+    ///     .arg("--from-autostart")
+    ///     .arg("--hey")
+    ///     .build();
+    /// ```
+    pub fn arg<S: Into<String>>(mut self, arg: S) -> Self {
+        self.args.push(arg.into());
+        self
+    }
+
+    /// Adds multiple arguments to pass to your app on startup.
+    ///
+    /// ## Examples
+    ///
+    /// ```no_run
+    /// Builder::new()
+    ///     .args(["--from-autostart", "--hey"])
+    ///     .build();
+    /// ```
+    pub fn args<I, S>(mut self, args: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<String>,
+    {
+        for arg in args {
+            self = self.arg(arg);
+        }
+        self
+    }
+
+    /// Sets whether to use launch agent or apple script to be used to enable auto start,
+    /// the builder's default is [`MacosLauncher::LaunchAgent`]
+    #[cfg(target_os = "macos")]
+    pub fn macos_launcher(mut self, macos_launcher: MacosLauncher) -> Self {
+        self.macos_launcher = macos_launcher;
+        self
+    }
+
+    pub fn build<R: Runtime>(self) -> TauriPlugin<R> {
+        PluginBuilder::new("autostart")
+            .invoke_handler(tauri::generate_handler![enable, disable, is_enabled])
+            .setup(move |app, _api| {
+                let mut builder = AutoLaunchBuilder::new();
+                builder.set_app_name(&app.package_info().name);
+                builder.set_args(&self.args);
+
+                let current_exe = current_exe()?;
+
+                #[cfg(windows)]
+                builder.set_app_path(&current_exe.display().to_string());
+
+                #[cfg(target_os = "macos")]
+                {
+                    builder.set_use_launch_agent(matches!(
+                        self.macos_launcher,
+                        MacosLauncher::LaunchAgent
+                    ));
+                    // on macOS, current_exe gives path to /Applications/Example.app/MacOS/Example
+                    // but this results in seeing a Unix Executable in macOS login items
+                    // It must be: /Applications/Example.app
+                    // If it didn't find exactly a single occurance of .app, it will default to
+                    // exe path to not break it.
+                    let exe_path = current_exe.canonicalize()?.display().to_string();
+                    let parts: Vec<&str> = exe_path.split(".app/").collect();
+                    let app_path = if parts.len() == 2
+                        && matches!(self.macos_launcher, MacosLauncher::AppleScript)
+                    {
+                        format!("{}.app", parts.first().unwrap())
+                    } else {
+                        exe_path
+                    };
+                    builder.set_app_path(&app_path);
+                }
+
+                #[cfg(target_os = "linux")]
+                if let Some(appimage) = app
+                    .env()
+                    .appimage
+                    .and_then(|p| p.to_str().map(|s| s.to_string()))
+                {
+                    builder.set_app_path(&appimage);
+                } else {
+                    builder.set_app_path(&current_exe.display().to_string());
+                }
+
+                app.manage(AutoLaunchManager(
+                    builder.build().map_err(|e| e.to_string())?,
+                ));
+                Ok(())
+            })
+            .build()
+    }
+}
+
 /// Initializes the plugin.
 ///
 /// `args` - are passed to your app on startup.
 pub fn init<R: Runtime>(
-    macos_launcher: MacosLauncher,
+    #[allow(unused)] macos_launcher: MacosLauncher,
     args: Option<Vec<&'static str>>,
 ) -> TauriPlugin<R> {
-    Builder::new("autostart")
-        .invoke_handler(tauri::generate_handler![enable, disable, is_enabled])
-        .setup(move |app, _api| {
-            let mut builder = AutoLaunchBuilder::new();
-            builder.set_app_name(&app.package_info().name);
-            if let Some(args) = args {
-                builder.set_args(&args);
-            }
-            builder.set_use_launch_agent(matches!(macos_launcher, MacosLauncher::LaunchAgent));
-
-            let current_exe = current_exe()?;
-
-            #[cfg(windows)]
-            builder.set_app_path(&current_exe.display().to_string());
-            #[cfg(target_os = "macos")]
-            {
-                // on macOS, current_exe gives path to /Applications/Example.app/MacOS/Example
-                // but this results in seeing a Unix Executable in macOS login items
-                // It must be: /Applications/Example.app
-                // If it didn't find exactly a single occurance of .app, it will default to
-                // exe path to not break it.
-                let exe_path = current_exe.canonicalize()?.display().to_string();
-                let parts: Vec<&str> = exe_path.split(".app/").collect();
-                let app_path =
-                    if parts.len() == 2 && matches!(macos_launcher, MacosLauncher::AppleScript) {
-                        format!("{}.app", parts.first().unwrap())
-                    } else {
-                        exe_path
-                    };
-                builder.set_app_path(&app_path);
-            }
-            #[cfg(target_os = "linux")]
-            if let Some(appimage) = app
-                .env()
-                .appimage
-                .and_then(|p| p.to_str().map(|s| s.to_string()))
-            {
-                builder.set_app_path(&appimage);
-            } else {
-                builder.set_app_path(&current_exe.display().to_string());
-            }
-
-            app.manage(AutoLaunchManager(
-                builder.build().map_err(|e| e.to_string())?,
-            ));
-            Ok(())
-        })
-        .build()
+    let mut builder = Builder::new();
+    if let Some(args) = args {
+        builder = builder.args(args)
+    }
+    #[cfg(target_os = "macos")]
+    {
+        builder = builder.macos_launcher(macos_launcher);
+    }
+    builder.build()
 }

plugins/barcode-scanner/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"

plugins/biometric/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"

plugins/cli/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"

plugins/clipboard-manager/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"

plugins/deep-link/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"

plugins/dialog/permissions/schemas/schema.json

@@ -49,7 +49,7 @@
           "minimum": 1.0
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"
@@ -111,7 +111,7 @@
           "type": "string"
         },
         "description": {
-          "description": "Human-readable description of what the permission does. Tauri internal convention is to use <h4> headings in markdown content for Tauri documentation generation purposes.",
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
           "type": [
             "string",
             "null"