Dart Tool System Paths

dart_tool_system_paths.dart

import 'dart:io' show Platform;

import 'package:file/file.dart';
import 'package:file/local.dart';

/// The standard system paths for a Dart [tool].
///
/// This class respects the following directory standards:
///
/// * On Linux, the [XDG Base Directory
///   Specification](https://specifications.freedesktop.org/basedir-spec/latest/).
/// * On MacOS, the
///   [Library](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html)
///   directory.
/// * On Windows, `%APPDATA%` and `%LOCALAPPDATA%`.
///
/// Note that the various directories might be overlapping or nested.
abstract class DartToolSystemPaths {
  /// The name of the tool.
  ///
  /// This should be a valid directory name on every operating system,
  /// typically containing only lower-case characters and underscores to ensure
  /// maximum compatibility and readability. For example, "my_dart_tool".
  final String tool;

  /// The file system to use.
  ///
  /// Defaults to [LocalFileSystem].
  final FileSystem fileSystem;

  /// The environment variables to use.
  ///
  /// Defaults to [Platform.environment].
  final Map<String, String>? environment;

  /// Constructs a [DartToolSystemPaths] instance for the given [tool]
  /// name.
  DartToolSystemPaths({
    required this.tool,
    FileSystem? fileSystem,
    Map<String, String>? environment,
  }) : fileSystem = fileSystem ?? const LocalFileSystem(),
       environment = environment ?? Platform.environment;

  /// The directory where [tool] can place its caches.
  ///
  /// The cache might at any point be purged by the operating system or user.
  /// Applications should be able to reconstruct any data stored here. If [tool]
  /// cannot handle data being purged, use [getDataDirectory] instead.
  ///
  /// On Windows, this method returns the same directory as [getDataDirectory]
  /// because both cache and data are stored under `%LOCALAPPDATA%`.
  ///
  /// Example Paths:
  /// - **macOS:** `~/Library/Caches/dart/my_dart_tool/`
  /// - **Linux:** `$XDG_CACHE_HOME/dart/my_dart_tool/` (defaults to
  ///   `~/.cache/dart/my_dart_tool/`)
  /// - **Windows:** `%LOCALAPPDATA%\dart\my_dart_tool\` (defaults to
  ///   `C:\Users\<YourUser>\AppData\Local\dart\my_dart_tool\`)
  Directory getCacheDirectory();

  /// The directory where [tool] can place its user-specific configuration.
  ///
  /// This directory is intended for application configuration, preferences, and
  /// settings. This directory may be synchronized across devices by the OS.
  ///
  /// On MacOS, if [plistFiles] is true, this returns the
  /// `~/Library/Preferences/dart/my_dart_tool/` directory, which is specifically for
  /// `.plist` files. If [plistFiles] is false, it returns the same directory as
  /// [getDataDirectory].
  ///
  /// Example Paths:
  /// - **macOS (plistFiles: true):** `~/Library/Preferences/dart/my_dart_tool/`
  ///   (should only contain `.plist` files)
  /// - **macOS (plistFiles: false):** `~/Library/Application Support/dart/my_dart_tool/`
  /// - **Linux:** `$XDG_CONFIG_HOME/dart/my_dart_tool/` (defaults to
  ///   `~/.config/dart/my_dart_tool/`)
  /// - **Windows:** `%APPDATA%\dart\my_dart_tool\` (defaults to
  ///   `C:\Users\<YourUser>\AppData\Roaming\dart\my_dart_tool\`)
  Directory getConfigDirectory({bool plistFiles = false});

  /// The directory where [tool] can place its user-specific application data.
  ///
  /// This directory is for general application data that is not configuration
  /// and is not expected to be purged (unlike cache). This might include
  /// databases, user-generated content, or application state.
  ///
  /// Example Paths:
  /// - **macOS:** `~/Library/Application Support/dart/my_dart_tool/`
  /// - **Linux:** `$XDG_DATA_HOME/dart/my_dart_tool/` (defaults to
  ///   `~/.local/share/dart/my_dart_tool/`)
  /// - **Windows:** `%LOCALAPPDATA%\dart\my_dart_tool\` (defaults to
  ///   `C:\Users\<YourUser>\AppData\Local\dart\my_dart_tool\`)
  Directory getDataDirectory();

  /// The directory where executables provided by the [tool] are placed.
  ///
  /// On Linux, this directory is already available on `PATH`. On Windows, and
  /// MacOS the tool should check if the directory is on the `PATH` and prompt
  /// the user to do so if it is not.
  ///
  /// Note that this directory is potentially shared with other tools.
  ///
  /// Example Paths:
  /// - **macOS:** `~/.local/bin/`
  /// - **Linux:** `~/.local/bin/`
  /// - **Windows:** `%LOCALAPPDATA%\dart\my_dart_tool\bin\` (defaults to
  ///   `C:\Users\<YourUser>\AppData\Local\dart\my_dart_tool\bin\`)
  Directory getExecutableDirectory();
}