Skip to main content

Crate cfgmatic_paths

Crate cfgmatic_paths 

Source
Expand description

Cross-platform configuration path discovery following XDG and platform conventions.

This crate provides a platform-agnostic way to discover configuration directories following the conventions of each operating system:

  • Unix/Linux: XDG Base Directory Specification
  • macOS CLI: XDG (same as Unix)
  • macOS GUI: Application Support directories
  • Windows: Known Folder IDs (AppData, ProgramData)

§Quick Start

use cfgmatic_paths::PathsBuilder;

// Create a path finder for your application
let finder = PathsBuilder::new("myapp").build();

// Get user config directories
let user_dirs = finder.user_dirs();
println!("User config dirs: {:?}", user_dirs);

// Ensure the primary user config directory exists
if let Ok(config_dir) = finder.ensure_user_config_dir() {
    println!("Config dir: {}", config_dir.display());
}

§Configuration Tiers

Configuration directories are organized into three tiers:

  1. User (ConfigTier::User): User-specific configs in home directory. Highest priority, typically writable.

  2. Local (ConfigTier::Local): Machine-specific configs. Medium priority, may be writable.

  3. System (ConfigTier::System): System-wide configs. Lowest priority, typically read-only.

§Platform Details

§Unix/Linux (XDG)

Uses the XDG Base Directory Specification:

  • User: $XDG_CONFIG_HOME/<app>/ (default: ~/.config/<app>/)
  • Legacy: ~/.<app>rc (optional, enabled by default)
  • System: $XDG_CONFIG_DIRS/<app>/ (default: /etc/xdg/<app>/)

§macOS

§CLI Applications

Uses XDG (same as Unix/Linux).

§GUI Applications (with macos-gui feature)

Uses macOS conventions:

  • User: ~/Library/Application Support/<bundle-id>/
  • System: /Library/Application Support/<bundle-id>/

§Windows

Uses Windows Known Folder IDs:

  • User Roaming: %APPDATA%\<Company>\<App>\
  • User Local: %LOCALAPPDATA%\<Company>\<App>\
  • System: %PROGRAMDATA%\<Company>\<App>\

§Testing

The crate provides abstractions for testing:

  • Env: Mock environment variables
  • Fs: Mock filesystem operations

These allow testing without modifying the actual environment or filesystem.

Modules§

finders
Platform-specific directory finder implementations.

Structs§

ConfigCandidate
Information about a configuration path candidate.
ConfigDiscovery
Result of a configuration discovery operation.
ConfigFileRule
Rule for finding a single configuration file.
ConfigRuleSet
Set of configuration file rules.
DirectoryInfo
Information about a configuration directory.
DiscoveryOptions
Options for configuration file discovery.
FragmentRule
Rule for configuration fragment directories (conf.d style).
PathFinder
Path finder for discovering configuration directories.
PathsBuilder
Builder for creating platform-specific path finders.
RuleBasedDiscovery
Result of rule-based configuration discovery.
RuleMatchResult
Result of searching for files by a single rule.
StdEnv
Standard environment using std::env.
StdFs
Standard filesystem using std::fs.
TierIterator
Iterator over configuration tiers in priority order.

Enums§

AppType
Type of application determines directory conventions.
ConfigTier
Configuration tier represents the priority level of a configuration source.
FilePattern
Pattern for matching configuration files.
PathStatus
Status of a configuration path.
SourceType
Type of configuration source.
TierSearchMode
How to search tiers for configuration files.

Traits§

DirectoryFinder
Trait for finding configuration directories on a specific platform.
Env
Abstraction over environment variables for testing.
Fs
Abstraction over filesystem operations for testing.

Functions§

config_file_path
Get the preferred configuration file path.
config_path
Get the preferred configuration path (without checking existence).
discover_config
Discover configuration with full diagnostics.
ensure_config_dir
Find or create the user configuration directory.
find_existing_dir
Find the first existing configuration directory.
get_all_dirs
Get all configuration directories with their metadata.