#platform #directory #user #application #paths #directories

platform-dirs

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

4 releases

✓ Uses Rust 2018 edition

new 0.2.0 Jun 11, 2019
0.1.2 Jun 8, 2019
0.1.1 Jun 8, 2019
0.1.0 Jun 8, 2019

11 downloads per month

MIT license

14KB
179 lines

platform-dirs-rs

crates.io

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

Note that the given directory paths are not guaranteed to exist.

Allows for specifying if an application is CLI or GUI based, since on macOS, CLI applications are expected to conform to the XDG spec, while GUI applications are expected to conform to the Standard Directories guidelines.

Uses the following standards:

Installation

Add the following to Cargo.toml:

[dependencies]
platform-dirs = "0.2.0"

Examples

Displaying paths

use platform_dirs::{AppDirs, AppUI, UserDirs};

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

    let app_dirs = AppDirs::new(Some("program-name"), AppUI::CommandLine).unwrap();
    dbg!(&app_dirs);
    // AppDirs {
    //     cache_dir: "/home/cjbassi/.cache/program-name",
    //     config_dir: "/home/cjbassi/.config/program-name",
    //     data_dir: "/home/cjbassi/.local/share/program-name",
    //     state_dir: "/home/cjbassi/.local/state/program-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"
    // }

    let home_dir = platform_dirs::home_dir().unwrap();
    dbg!(&home_dir);
    // "/home/cjbassi"
}

Opening config file

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

use platform_dirs::{AppDirs, AppUI};

fn main() {
    let app_dirs = AppDirs::new(Some("program-name"), AppUI::CommandLine).unwrap();

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

    let config_file_path = app_dirs.config_dir.join("config-file");
    let f = if config_file_path.exists() {
        File::open(config_file_path).unwrap()
    } else {
        File::create(config_file_path).unwrap()
    };
}

Path list

AppDirs

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

UserDirs

Directory Windows Unix (excluding macOS) macOS
desktop_dir {FOLDERID_Desktop} (C:\Users\%USERNAME%\Desktop) XDG_DESKTOP_DIR ($HOME/Desktop) $HOME/Desktop
document_dir {FOLDERID_Documents} (C:\Users\%USERNAME%\Documents) XDG_DOCUMENTS_DIR ($HOME/Documents) $HOME/Documents
download_dir {FOLDERID_Downloads} (C:\Users\%USERNAME%\Downloads) XDG_DOWNLOAD_DIR ($HOME/Downloads) $HOME/Downloads
music_dir {FOLDERID_Music} (C:\Users\%USERNAME%\Music) XDG_MUSIC_DIR ($HOME/Music) $HOME/Music
picture_dir {FOLDERID_Pictures} (C:\Users\%USERNAME%\Pictures) XDG_PICTURES_DIR ($HOME/Pictures) $HOME/Pictures
public_dir {FOLDERID_Public} (C:\Users\%USERNAME%\Public) XDG_PUBLICSHARE_DIR ($HOME/Public) $HOME/Public
video_dir {FOLDERID_Videos} (C:\Users\%USERNAME%\Videos) XDG_VIDEOS_DIR ($HOME/Videos) $HOME/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
    • UserDirs' fields are no longer Options
    • the struct fields are now publicly accessible
    • combines the ProjectDirs struct into AppDirs
  • adds state_dir to AppDirs
    • documented here at the bottom
    • 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

Dependencies

~687KB