platform-dirs 0.3.0

A library for obtaining platform dependant directory paths for application and user directories
Documentation

platform-dirs-rs

crates.io docs.rs

A Rust library for obtaining platform dependent directory paths for application and user directories.

Uses the following standards:

Installation

Add the following to your Cargo.toml:

[dependencies]
platform-dirs = "0.3.0"

Examples

Obtaining paths

use platform_dirs::{AppDirs, UserDirs};

fn main() {
    let app_dirs = AppDirs::new(Some("name"), false).unwrap();
    dbg!(&app_dirs);
    // AppDirs {
    //     cache_dir: "/home/cjbassi/.cache/name",
    //     config_dir: "/home/cjbassi/.config/name",
    //     data_dir: "/home/cjbassi/.local/share/name",
    //     state_dir: "/home/cjbassi/.local/state/name"
    // }

    let user_dirs = UserDirs::new().unwrap();
    dbg!(&user_dirs);
    // UserDirs {
    //     desktop_dir: "/home/cjbassi/Desktop",
    //     document_dir: "/home/cjbassi/Documents",
    //     download_dir: "/home/cjbassi/Downloads",
    //     music_dir: "/home/cjbassi/Music",
    //     picture_dir: "/home/cjbassi/Pictures",
    //     public_dir: "/home/cjbassi/Public",
    //     video_dir: "/home/cjbassi/Videos"
    // }
}

Opening config file

use std::fs::{self, File};

use platform_dirs::AppDirs;

fn main() {
    let app_dirs = AppDirs::new(Some("name"), true).unwrap();
    let config_file_path = app_dirs.config_dir.join("config-file");

    fs::create_dir_all(&app_dirs.config_dir).unwrap();

    let file = if config_file_path.exists() {
        File::open(config_file_path).unwrap()
    } else {
        File::create(config_file_path).unwrap()
    };
}

Path list

AppDirs

Directory Windows Linux/*BSD macOS
cache_dir %LOCALAPPDATA% (C:\Users\%USERNAME%\AppData\Local) $XDG_CACHE_HOME (~/.cache) ~/Library/Caches
config_dir %APPDATA% (C:\Users\%USERNAME%\AppData\Roaming) $XDG_CONFIG_HOME (~/.config) ~/Library/Application Support
data_dir %LOCALAPPDATA% (C:\Users\%USERNAME%\AppData\Local) $XDG_DATA_HOME (~/.local/share) ~/Library/Application Support
state_dir %LOCALAPPDATA% (C:\Users\%USERNAME%\AppData\Local) $XDG_STATE_HOME (~/.local/state) ~/Library/Application Support

UserDirs

Directory Windows Linux/*BSD macOS
desktop_dir {FOLDERID_Desktop} (C:\Users\%USERNAME%\Desktop) $XDG_DESKTOP_DIR (~/Desktop) ~/Desktop
document_dir {FOLDERID_Documents} (C:\Users\%USERNAME%\Documents) $XDG_DOCUMENTS_DIR (~/Documents) ~/Documents
download_dir {FOLDERID_Downloads} (C:\Users\%USERNAME%\Downloads) $XDG_DOWNLOAD_DIR (~/Downloads) ~/Downloads
music_dir {FOLDERID_Music} (C:\Users\%USERNAME%\Music) $XDG_MUSIC_DIR (~/Music) ~/Music
picture_dir {FOLDERID_Pictures} (C:\Users\%USERNAME%\Pictures) $XDG_PICTURES_DIR (~/Pictures) ~/Pictures
public_dir {FOLDERID_Public} (C:\Users\%USERNAME%\Public) $XDG_PUBLICSHARE_DIR (~/Public) ~/Public
video_dir {FOLDERID_Videos} (C:\Users\%USERNAME%\Videos) $XDG_VIDEOS_DIR (~/Videos) ~/Movies

Comparisons

platform-dirs differs from dirs-rs and directories-rs in several ways:

  • allows for using the XDG spec on macOS for CLI apps
  • changes the config directory on macOS from Library/Preferences to Library/Application Support
    • Library/Preferences is supposed to be used for macOS unique plist preferences: info
  • only includes directories that are cross platform
    • AppDirs:
      • removes data_local_dir
    • UserDirs:
      • removes runtime_dir, executable_dir
  • provides a simpler API than directories-rs
    • the fields of UserDirs are no longer Options
    • the struct fields are now publicly accessible
    • combines the ProjectDirs struct into AppDirs
  • adds state_dir to AppDirs
    • documentation can be found here at the bottom of the page
    • used for stateful application data like logs, history, etc
  • on Linux, returns default platforms values for the UserDirs if they are not set instead of returning None