tauri_utils/
lib.rs

1// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
2// SPDX-License-Identifier: Apache-2.0
3// SPDX-License-Identifier: MIT
4
5//! This crate contains common code that is reused in many places and offers useful utilities like parsing configuration files, detecting platform triples, injecting the CSP, and managing assets.
6
7#![doc(
8  html_logo_url = "https://github.com/tauri-apps/tauri/raw/dev/.github/icon.png",
9  html_favicon_url = "https://github.com/tauri-apps/tauri/raw/dev/.github/icon.png"
10)]
11#![warn(missing_docs, rust_2018_idioms)]
12#![allow(clippy::deprecated_semver)]
13
14use std::{
15  ffi::OsString,
16  fmt::Display,
17  path::{Path, PathBuf},
18};
19
20use semver::Version;
21use serde::{Deserialize, Deserializer, Serialize, Serializer};
22
23pub mod acl;
24pub mod assets;
25pub mod config;
26pub mod config_v1;
27#[cfg(feature = "html-manipulation")]
28pub mod html;
29pub mod io;
30pub mod mime_type;
31pub mod platform;
32pub mod plugin;
33/// Prepare application resources and sidecars.
34#[cfg(feature = "resources")]
35pub mod resources;
36#[cfg(feature = "build")]
37pub mod tokens;
38
39#[cfg(feature = "build")]
40pub mod build;
41
42/// Application pattern.
43pub mod pattern;
44
45/// `tauri::App` package information.
46#[derive(Debug, Clone)]
47pub struct PackageInfo {
48  /// App name
49  pub name: String,
50  /// App version
51  pub version: Version,
52  /// The crate authors.
53  pub authors: &'static str,
54  /// The crate description.
55  pub description: &'static str,
56  /// The crate name.
57  pub crate_name: &'static str,
58}
59
60#[allow(deprecated)]
61mod window_effects {
62  use super::*;
63
64  #[derive(Debug, PartialEq, Eq, Clone, Copy, Deserialize, Serialize)]
65  #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
66  #[serde(rename_all = "camelCase")]
67  /// Platform-specific window effects
68  pub enum WindowEffect {
69    /// A default material appropriate for the view's effectiveAppearance. **macOS 10.14-**
70    #[deprecated(
71      since = "macOS 10.14",
72      note = "You should instead choose an appropriate semantic material."
73    )]
74    AppearanceBased,
75    /// **macOS 10.14-**
76    #[deprecated(since = "macOS 10.14", note = "Use a semantic material instead.")]
77    Light,
78    /// **macOS 10.14-**
79    #[deprecated(since = "macOS 10.14", note = "Use a semantic material instead.")]
80    Dark,
81    /// **macOS 10.14-**
82    #[deprecated(since = "macOS 10.14", note = "Use a semantic material instead.")]
83    MediumLight,
84    /// **macOS 10.14-**
85    #[deprecated(since = "macOS 10.14", note = "Use a semantic material instead.")]
86    UltraDark,
87    /// **macOS 10.10+**
88    Titlebar,
89    /// **macOS 10.10+**
90    Selection,
91    /// **macOS 10.11+**
92    Menu,
93    /// **macOS 10.11+**
94    Popover,
95    /// **macOS 10.11+**
96    Sidebar,
97    /// **macOS 10.14+**
98    HeaderView,
99    /// **macOS 10.14+**
100    Sheet,
101    /// **macOS 10.14+**
102    WindowBackground,
103    /// **macOS 10.14+**
104    HudWindow,
105    /// **macOS 10.14+**
106    FullScreenUI,
107    /// **macOS 10.14+**
108    Tooltip,
109    /// **macOS 10.14+**
110    ContentBackground,
111    /// **macOS 10.14+**
112    UnderWindowBackground,
113    /// **macOS 10.14+**
114    UnderPageBackground,
115    /// Mica effect that matches the system dark preference **Windows 11 Only**
116    Mica,
117    /// Mica effect with dark mode but only if dark mode is enabled on the system **Windows 11 Only**
118    MicaDark,
119    /// Mica effect with light mode **Windows 11 Only**
120    MicaLight,
121    /// Tabbed effect that matches the system dark preference **Windows 11 Only**
122    Tabbed,
123    /// Tabbed effect with dark mode but only if dark mode is enabled on the system **Windows 11 Only**
124    TabbedDark,
125    /// Tabbed effect with light mode **Windows 11 Only**
126    TabbedLight,
127    /// **Windows 7/10/11(22H1) Only**
128    ///
129    /// ## Notes
130    ///
131    /// This effect has bad performance when resizing/dragging the window on Windows 11 build 22621.
132    Blur,
133    /// **Windows 10/11 Only**
134    ///
135    /// ## Notes
136    ///
137    /// This effect has bad performance when resizing/dragging the window on Windows 10 v1903+ and Windows 11 build 22000.
138    Acrylic,
139  }
140
141  /// Window effect state **macOS only**
142  ///
143  /// <https://developer.apple.com/documentation/appkit/nsvisualeffectview/state>
144  #[derive(Debug, PartialEq, Eq, Clone, Copy, Deserialize, Serialize)]
145  #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
146  #[serde(rename_all = "camelCase")]
147  pub enum WindowEffectState {
148    /// Make window effect state follow the window's active state
149    FollowsWindowActiveState,
150    /// Make window effect state always active
151    Active,
152    /// Make window effect state always inactive
153    Inactive,
154  }
155}
156
157pub use window_effects::{WindowEffect, WindowEffectState};
158
159/// How the window title bar should be displayed on macOS.
160#[derive(Debug, Clone, PartialEq, Eq, Copy, Default)]
161#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
162#[non_exhaustive]
163pub enum TitleBarStyle {
164  /// A normal title bar.
165  #[default]
166  Visible,
167  /// Makes the title bar transparent, so the window background color is shown instead.
168  ///
169  /// Useful if you don't need to have actual HTML under the title bar. This lets you avoid the caveats of using `TitleBarStyle::Overlay`. Will be more useful when Tauri lets you set a custom window background color.
170  Transparent,
171  /// Shows the title bar as a transparent overlay over the window's content.
172  ///
173  /// Keep in mind:
174  /// - The height of the title bar is different on different OS versions, which can lead to window the controls and title not being where you don't expect.
175  /// - You need to define a custom drag region to make your window draggable, however due to a limitation you can't drag the window when it's not in focus <https://github.com/tauri-apps/tauri/issues/4316>.
176  /// - The color of the window title depends on the system theme.
177  Overlay,
178}
179
180impl Serialize for TitleBarStyle {
181  fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
182  where
183    S: Serializer,
184  {
185    serializer.serialize_str(self.to_string().as_ref())
186  }
187}
188
189impl<'de> Deserialize<'de> for TitleBarStyle {
190  fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
191  where
192    D: Deserializer<'de>,
193  {
194    let s = String::deserialize(deserializer)?;
195    Ok(match s.to_lowercase().as_str() {
196      "transparent" => Self::Transparent,
197      "overlay" => Self::Overlay,
198      _ => Self::Visible,
199    })
200  }
201}
202
203impl Display for TitleBarStyle {
204  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
205    write!(
206      f,
207      "{}",
208      match self {
209        Self::Visible => "Visible",
210        Self::Transparent => "Transparent",
211        Self::Overlay => "Overlay",
212      }
213    )
214  }
215}
216
217/// System theme.
218#[derive(Debug, Copy, Clone, PartialEq, Eq)]
219#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
220#[non_exhaustive]
221pub enum Theme {
222  /// Light theme.
223  Light,
224  /// Dark theme.
225  Dark,
226}
227
228impl Serialize for Theme {
229  fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
230  where
231    S: Serializer,
232  {
233    serializer.serialize_str(self.to_string().as_ref())
234  }
235}
236
237impl<'de> Deserialize<'de> for Theme {
238  fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
239  where
240    D: Deserializer<'de>,
241  {
242    let s = String::deserialize(deserializer)?;
243    Ok(match s.to_lowercase().as_str() {
244      "dark" => Self::Dark,
245      _ => Self::Light,
246    })
247  }
248}
249
250impl Display for Theme {
251  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
252    write!(
253      f,
254      "{}",
255      match self {
256        Self::Light => "light",
257        Self::Dark => "dark",
258      }
259    )
260  }
261}
262
263/// Information about environment variables.
264#[derive(Debug, Clone)]
265#[non_exhaustive]
266pub struct Env {
267  /// The APPIMAGE environment variable.
268  #[cfg(target_os = "linux")]
269  pub appimage: Option<std::ffi::OsString>,
270  /// The APPDIR environment variable.
271  #[cfg(target_os = "linux")]
272  pub appdir: Option<std::ffi::OsString>,
273  /// The command line arguments of the current process.
274  pub args_os: Vec<OsString>,
275}
276
277#[allow(clippy::derivable_impls)]
278impl Default for Env {
279  fn default() -> Self {
280    let args_os = std::env::args_os().collect();
281    #[cfg(target_os = "linux")]
282    {
283      let env = Self {
284        #[cfg(target_os = "linux")]
285        appimage: std::env::var_os("APPIMAGE"),
286        #[cfg(target_os = "linux")]
287        appdir: std::env::var_os("APPDIR"),
288        args_os,
289      };
290      if env.appimage.is_some() || env.appdir.is_some() {
291        // validate that we're actually running on an AppImage
292        // an AppImage is mounted to `/$TEMPDIR/.mount_${appPrefix}${hash}`
293        // see <https://github.com/AppImage/AppImageKit/blob/1681fd84dbe09c7d9b22e13cdb16ea601aa0ec47/src/runtime.c#L501>
294        // note that it is safe to use `std::env::current_exe` here since we just loaded an AppImage.
295        let is_temp = std::env::current_exe()
296          .map(|p| {
297            p.display()
298              .to_string()
299              .starts_with(&format!("{}/.mount_", std::env::temp_dir().display()))
300          })
301          .unwrap_or(true);
302
303        if !is_temp {
304          log::warn!("`APPDIR` or `APPIMAGE` environment variable found but this application was not detected as an AppImage; this might be a security issue.");
305        }
306      }
307      env
308    }
309    #[cfg(not(target_os = "linux"))]
310    {
311      Self { args_os }
312    }
313  }
314}
315
316/// The result type of `tauri-utils`.
317pub type Result<T> = std::result::Result<T, Error>;
318
319/// The error type of `tauri-utils`.
320#[derive(Debug, thiserror::Error)]
321#[non_exhaustive]
322pub enum Error {
323  /// Target triple architecture error
324  #[error("Unable to determine target-architecture")]
325  Architecture,
326  /// Target triple OS error
327  #[error("Unable to determine target-os")]
328  Os,
329  /// Target triple environment error
330  #[error("Unable to determine target-environment")]
331  Environment,
332  /// Tried to get resource on an unsupported platform
333  #[error("Unsupported platform for reading resources")]
334  UnsupportedPlatform,
335  /// Get parent process error
336  #[error("Could not get parent process")]
337  ParentProcess,
338  /// Get parent process PID error
339  #[error("Could not get parent PID")]
340  ParentPid,
341  /// Get child process error
342  #[error("Could not get child process")]
343  ChildProcess,
344  /// IO error
345  #[error("{0}")]
346  Io(#[from] std::io::Error),
347  /// Invalid pattern.
348  #[error("invalid pattern `{0}`. Expected either `brownfield` or `isolation`.")]
349  InvalidPattern(String),
350  /// Invalid glob pattern.
351  #[cfg(feature = "resources")]
352  #[error("{0}")]
353  GlobPattern(#[from] glob::PatternError),
354  /// Failed to use glob pattern.
355  #[cfg(feature = "resources")]
356  #[error("`{0}`")]
357  Glob(#[from] glob::GlobError),
358  /// Glob pattern did not find any results.
359  #[cfg(feature = "resources")]
360  #[error("glob pattern {0} path not found or didn't match any files.")]
361  GlobPathNotFound(String),
362  /// Error walking directory.
363  #[cfg(feature = "resources")]
364  #[error("{0}")]
365  WalkdirError(#[from] walkdir::Error),
366  /// Not allowed to walk dir.
367  #[cfg(feature = "resources")]
368  #[error("could not walk directory `{0}`, try changing `allow_walk` to true on the `ResourcePaths` constructor.")]
369  NotAllowedToWalkDir(std::path::PathBuf),
370  /// Resource path doesn't exist
371  #[cfg(feature = "resources")]
372  #[error("resource path `{0}` doesn't exist")]
373  ResourcePathNotFound(std::path::PathBuf),
374}
375
376/// Reconstructs a path from its components using the platform separator then converts it to String and removes UNC prefixes on Windows if it exists.
377pub fn display_path<P: AsRef<Path>>(p: P) -> String {
378  dunce::simplified(&p.as_ref().components().collect::<PathBuf>())
379    .display()
380    .to_string()
381}
382
383/// Write the file only if the content of the existing file (if any) is different.
384///
385/// This will always write unless the file exists with identical content.
386pub fn write_if_changed<P, C>(path: P, content: C) -> std::io::Result<()>
387where
388  P: AsRef<Path>,
389  C: AsRef<[u8]>,
390{
391  if let Ok(existing) = std::fs::read(&path) {
392    if existing == content.as_ref() {
393      return Ok(());
394    }
395  }
396
397  std::fs::write(path, content)
398}
tauri_utils/lib.rs

tauri_utils/
lib.rs
