rust-xdg

https://github.com/whitequark/rust-xdg
Admin
A Rust library that makes it easy to follow X Desktop Group specifications, currently implementing...
Tokens:5,815
Snippets:33
Trust Score:9.7
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Base XDG Directory Paths (Rust)

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Shows how to access the underlying XDG base directory paths directly using methods like `get_config_home`, `get_data_home`, `get_cache_home`, `get_state_home`, `get_config_dirs`, `get_data_dirs`, and `get_runtime_directory` from the `xdg` crate for advanced use cases.

```rust
use xdg::BaseDirectories;

fn print_xdg_paths() {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // User-specific directories (with prefix applied)
    if let Some(config_home) = xdg_dirs.get_config_home() {
        println!("Config home: {:?}", config_home);  // ~/.config/myapp
    }

    if let Some(data_home) = xdg_dirs.get_data_home() {
        println!("Data home: {:?}", data_home);  // ~/.local/share/myapp
    }

    if let Some(cache_home) = xdg_dirs.get_cache_home() {
        println!("Cache home: {:?}", cache_home);  // ~/.cache/myapp
    }

    if let Some(state_home) = xdg_dirs.get_state_home() {
        println!("State home: {:?}", state_home);  // ~/.local/state/myapp
    }

    // System directories (with prefix applied)
    let config_dirs = xdg_dirs.get_config_dirs();
    println!("Config dirs: {:?}", config_dirs);  // [/etc/xdg/myapp]

    let data_dirs = xdg_dirs.get_data_dirs();
    println!("Data dirs: {:?}", data_dirs);  // [/usr/local/share/myapp, /usr/share/myapp]

    // Runtime directory (requires XDG_RUNTIME_DIR to be set)
    match xdg_dirs.get_runtime_directory() {
        Ok(runtime_dir) => println!("Runtime dir: {:?}", runtime_dir),
        Err(e) => println!("Runtime dir unavailable: {}", e),
    }
}

```

--------------------------------

### Get File Paths Without Creating Directories (Rust)

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Demonstrates how to use `get_*_file` methods from `xdg::BaseDirectories` to obtain paths for configuration, data, cache, and state files without actually creating the directories. This is useful for previewing file locations or checking for existing files.

```rust
use xdg::BaseDirectories;

fn preview_file_locations() {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Get where config file would be placed (doesn't create directory)
    if let Some(config_path) = xdg_dirs.get_config_file("settings.json") {
        println!("Config would be at: {:?}", config_path);
        // ~/.config/myapp/settings.json
    }

    // Get where data file would be placed
    if let Some(data_path) = xdg_dirs.get_data_file("database.sqlite") {
        println!("Database would be at: {:?}", data_path);
        // ~/.local/share/myapp/database.sqlite
    }

    // Get where cache file would be placed
    if let Some(cache_path) = xdg_dirs.get_cache_file("temp.dat") {
        println!("Cache would be at: {:?}", cache_path);
        // ~/.cache/myapp/temp.dat
    }

    // Get where state file would be placed
    if let Some(state_path) = xdg_dirs.get_state_file("window.state") {
        println!("State would be at: {:?}", state_path);
        // ~/.local/state/myapp/window.state
    }

    // Runtime file path (may fail if XDG_RUNTIME_DIR not set)
    match xdg_dirs.get_runtime_file("daemon.pid") {
        Ok(runtime_path) => println!("Runtime would be at: {:?}", runtime_path),
        Err(e) => println!("Cannot determine runtime path: {}", e),
    }
}

```

--------------------------------

### Create BaseDirectories Instance in Rust

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Demonstrates creating a `BaseDirectories` instance using `rust-xdg`. It shows how to create a basic instance, one with an application prefix, and another with both a prefix and a profile for multi-profile support. These instances are crucial for accessing XDG-compliant directories.

```rust
use xdg::BaseDirectories;

// Create a basic instance (no prefix)
let xdg_dirs = BaseDirectories::new();

// Create with application prefix - recommended for most applications
// Files will be stored under ~/.config/myapp/, ~/.local/share/myapp/, etc.
let xdg_dirs = BaseDirectories::with_prefix("myapp");

// Create with prefix and profile for multi-profile support
// User files: ~/.config/myapp/work/, ~/.local/share/myapp/work/
// System files: /usr/share/myapp/ (no profile in system dirs)
let xdg_dirs = BaseDirectories::with_profile("myapp", "work");
```

--------------------------------

### Place and Find Data Files in Rust

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Demonstrates how to use `place_data_file` to write application data (like databases) and `find_data_file` to read them. It searches the user's data directory (`~/.local/share/myapp/`) and then system directories (`/usr/local/share/myapp/`, `/usr/share/myapp/`).

```rust
use std::fs::File;
use std::io::{Read, Write};
use xdg::BaseDirectories;

fn manage_data_files() -> std::io::Result<()> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Write data file to ~/.local/share/myapp/database.db
    let db_path = xdg_dirs
        .place_data_file("database.db")
        .expect("cannot create data directory");

    let mut db_file = File::create(&db_path)?;
    db_file.write_all(b"data content")?;
    println!("Database created at: {:?}", db_path);

    // Find data file - searches user dir then system dirs
    // ~/.local/share/myapp/, /usr/local/share/myapp/, /usr/share/myapp/
    if let Some(asset_path) = xdg_dirs.find_data_file("logo.png") {
        let mut file = File::open(asset_path)?;
        let mut buffer = Vec::new();
        file.read_to_end(&mut buffer)?;
        println!("Loaded {} bytes", buffer.len());
    }

    Ok(())
}
```

--------------------------------

### Create Directories for App Organization (Rust)

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Demonstrates using `create_*_directory` methods from the `xdg` crate to create nested directories within XDG locations for organizing application files. It shows how to create config, data, cache, and state directories and then create files within them.

```rust
use std::fs::File;
use xdg::BaseDirectories;

fn setup_app_directories() -> std::io::Result<()> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Create config directory: ~/.config/myapp/themes/
    let themes_dir = xdg_dirs.create_config_directory("themes")?;
    println!("Themes directory: {:?}", themes_dir);

    // Create data directory: ~/.local/share/myapp/plugins/
    let plugins_dir = xdg_dirs.create_data_directory("plugins")?;
    println!("Plugins directory: {:?}", plugins_dir);

    // Create cache directory: ~/.cache/myapp/downloads/
    let downloads_dir = xdg_dirs.create_cache_directory("downloads")?;
    println!("Downloads cache: {:?}", downloads_dir);

    // Create state directory: ~/.local/state/myapp/sessions/
    let sessions_dir = xdg_dirs.create_state_directory("sessions")?;
    println!("Sessions directory: {:?}", sessions_dir);

    // Now create files within these directories
    File::create(themes_dir.join("dark.toml"))?;
    File::create(plugins_dir.join("manifest.json"))?;

    Ok(())
}

```

--------------------------------

### Work with Runtime Files (Sockets) in Rust

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Demonstrates creating and finding runtime files, specifically a Unix socket, using `place_runtime_file` and `find_runtime_file`. These files are typically used for inter-process communication and are stored in `$XDG_RUNTIME_DIR`.

```rust
use std::os::unix::net::UnixListener;
use xdg::BaseDirectories;

fn setup_runtime_socket() -> std::io::Result<()> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Check if runtime directory is available
    if !xdg_dirs.has_runtime_directory() {
        eprintln!("XDG_RUNTIME_DIR not available");
        return Ok(());
    }

    // Place socket at $XDG_RUNTIME_DIR/myapp/control.sock
    let socket_path = xdg_dirs.place_runtime_file("control.sock")?;
    println!("Creating socket at: {:?}", socket_path);

    // Remove existing socket if present
    let _ = std::fs::remove_file(&socket_path);

    let listener = UnixListener::bind(&socket_path)?;
    println!("Listening on socket...");

    // Find runtime file
    if let Some(path) = xdg_dirs.find_runtime_file("control.sock") {
        println!("Socket found at: {:?}", path);
    }

    Ok(())
}
```

--------------------------------

### Find All Configuration Files with rust-xdg

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Demonstrates iterating over all matching configuration files across XDG directories using `rust-xdg`. The `find_config_files` method returns an iterator that yields paths in order of lowest to highest priority (system directories first, then user directory). This is useful for merging configurations.

```rust
use std::fs;
use xdg::BaseDirectories;

fn merge_configs() {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Iterate through all config files (system dirs first, then user dir)
    // Priority order: /usr/share/..., /usr/local/share/..., ~/.config/...
    for config_path in xdg_dirs.find_config_files("plugins.conf") {
        println!("Loading config from: {:?}", config_path);
        if let Ok(content) = fs::read_to_string(&config_path) {
            // Process each config, later ones override earlier ones
            println!("Content: {}", content);
        }
    }
}
```

--------------------------------

### Save Configuration File with rust-xdg

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Illustrates how to save a configuration file using `rust-xdg`. The `place_config_file` method ensures the necessary directory structure is created within the XDG configuration home, and then a `File` is created and written to. This function returns a `std::io::Result`.

```rust
use std::fs::File;
use std::io::Write;
use xdg::BaseDirectories;

fn save_config() -> std::io::Result<()> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Creates ~/.config/myapp/ directory if needed
    // Returns path like: ~/.config/myapp/config.toml
    let config_path = xdg_dirs
        .place_config_file("config.toml")
        .expect("cannot create configuration directory");

    let mut config_file = File::create(&config_path)?;
    writeln!(config_file, "[settings]")?;
    writeln!(config_file, "theme = \"dark\"")?;

    println!("Config saved to: {:?}", config_path);
    Ok(())
}
```

--------------------------------

### Place and Find State Files in Rust

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Illustrates managing application state files (logs, history) with `place_state_file` and `find_state_file`. These files persist across sessions and are stored in `~/.local/state/myapp/`.

```rust
use std::fs::{File, OpenOptions};
use std::io::{BufRead, BufReader, Write};
use xdg::BaseDirectories;

fn manage_state() -> std::io::Result<()> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Place state file at ~/.local/state/myapp/history.log
    let history_path = xdg_dirs
        .place_state_file("history.log")
        .expect("cannot create state directory");

    // Append to history log
    let mut file = OpenOptions::new()
        .create(true)
        .append(true)
        .open(&history_path)?;
    writeln!(file, "2024-01-15: User opened file.txt")?;

    // Read history
    if let Some(path) = xdg_dirs.find_state_file("history.log") {
        let reader = BufReader::new(File::open(path)?);
        for line in reader.lines().take(10) {
            println!("History: {}", line?);
        }
    }

    Ok(())
}
```

--------------------------------

### Find Configuration File with rust-xdg

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Shows how to find an existing configuration file using `rust-xdg`. The `find_config_file` method searches the user's XDG config directory first, then system-wide directories. It returns an `Option<String>` representing the path to the first found file, or `None` if not found.

```rust
use std::fs;
use xdg::BaseDirectories;

fn load_config() -> Option<String> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Searches: ~/.config/myapp/config.toml, then /etc/xdg/myapp/config.toml
    match xdg_dirs.find_config_file("config.toml") {
        Some(path) => {
            println!("Found config at: {:?}", path);
            fs::read_to_string(path).ok()
        }
        None => {
            println!("No config file found, using defaults");
            None
        }
    }
}
```

--------------------------------

### Serde Serialization/Deserialization Support (Rust)

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Shows how to enable and use Serde for serializing and deserializing `BaseDirectories` instances. This requires enabling the `serde` feature in the `Cargo.toml` file.

```rust
// Cargo.toml:
// [dependencies]
// xdg = { version = "3.0", features = ["serde"] }

#[cfg(feature = "serde")]
use serde::{Serialize, Deserialize};
use xdg::BaseDirectories;

#[cfg(feature = "serde")]
fn serialize_directories() -> Result<(), Box<dyn std::error::Error>> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Serialize to JSON
    let json = serde_json::to_string_pretty(&xdg_dirs)?;
    println!("Serialized:\n{}", json);

    // Deserialize back
    let restored: BaseDirectories = serde_json::from_str(&json)?;
    println!("Restored config home: {:?}", restored.get_config_home());

    Ok(())
}

```

--------------------------------

### Place and Find Cache Files in Rust

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Shows how to manage cache files using `place_cache_file` for writing and `find_cache_file` for reading. Cache files are stored in `XDG_CACHE_HOME` (typically `~/.cache/`) and are suitable for transient, regeneratable data.

```rust
use std::fs::{self, File};
use std::io::Write;
use xdg::BaseDirectories;

fn manage_cache() -> std::io::Result<()> {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // Place cache file at ~/.cache/myapp/thumbnails/image_001.jpg
    let cache_path = xdg_dirs
        .place_cache_file("thumbnails/image_001.jpg")
        .expect("cannot create cache directory");

    File::create(&cache_path)?.write_all(b"thumbnail data")?;
    println!("Cache stored at: {:?}", cache_path);

    // Find existing cache file
    if let Some(cached) = xdg_dirs.find_cache_file("thumbnails/image_001.jpg") {
        let data = fs::read(&cached)?;
        println!("Cache hit: {} bytes", data.len());
    } else {
        println!("Cache miss - regenerating...");
    }

    Ok(())
}
```

--------------------------------

### List Files in XDG Directories (Rust)

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Illustrates how to use `list_*_files` methods from the `xdg` crate to enumerate files within subdirectories across user and system XDG locations. It covers listing all files, unique files (with user overrides), config files, and cache files.

```rust
use xdg::BaseDirectories;

fn list_available_plugins() {
    let xdg_dirs = BaseDirectories::with_prefix("myapp");

    // List all plugin files from user and system directories
    // Searches: ~/.local/share/myapp/plugins/, /usr/share/myapp/plugins/, etc.
    let all_plugins = xdg_dirs.list_data_files("plugins");
    println!("All plugin files (may include duplicates):");
    for plugin in &all_plugins {
        println!("  {:?}", plugin);
    }

    // List with deduplication - only first occurrence of each filename
    let unique_plugins = xdg_dirs.list_data_files_once("plugins");
    println!("\nUnique plugins (user overrides system):");
    for plugin in &unique_plugins {
        println!("  {:?}", plugin);
    }

    // List config files
    let configs = xdg_dirs.list_config_files("snippets");
    println!("\nSnippet files: {}", configs.len());

    // List cache files
    let cached = xdg_dirs.list_cache_files("thumbnails");
    println!("Cached thumbnails: {}", cached.len());
}

```

--------------------------------

### Add rust-xdg Dependency to Cargo.toml

Source: https://github.com/whitequark/rust-xdg/blob/main/README.md

This snippet shows how to add the rust-xdg library as a dependency to your Rust project's Cargo.toml file. It specifies the latest version of the xdg crate to be used.

```toml
[dependencies]
xdg = "^2.6"

```

--------------------------------

### Access Raw XDG Directory Fields (Rust)

Source: https://context7.com/whitequark/rust-xdg/llms.txt

Illustrates how to access the raw, un-prefixed XDG directory paths directly from the `BaseDirectories` struct. This allows for more granular control or inspection of the underlying directory structure.

```rust
use xdg::BaseDirectories;

fn inspect_raw_directories() {
    let xdg_dirs = BaseDirectories::with_profile("myapp", "default");

    // Access raw paths (without prefixes)
    println!("Shared prefix: {:?}", xdg_dirs.shared_prefix);  // "myapp"
    println!("User prefix: {:?}", xdg_dirs.user_prefix);      // "myapp/default"

    // Raw home directories (without any prefix)
    if let Some(ref data_home) = xdg_dirs.data_home {
        println!("Raw data home: {:?}", data_home);  // ~/.local/share
    }

    if let Some(ref config_home) = xdg_dirs.config_home {
        println!("Raw config home: {:?}", config_home);  // ~/.config
    }

    if let Some(ref cache_home) = xdg_dirs.cache_home {
        println!("Raw cache home: {:?}", cache_home);  // ~/.cache
    }

    if let Some(ref state_home) = xdg_dirs.state_home {
        println!("Raw state home: {:?}", state_home);  // ~/.local/state
    }

    // Raw system directories
    println!("Raw data dirs: {:?}", xdg_dirs.data_dirs);
    // [/usr/local/share, /usr/share]

    println!("Raw config dirs: {:?}", xdg_dirs.config_dirs);
    // [/etc/xdg]

    if let Some(ref runtime_dir) = xdg_dirs.runtime_dir {
        println!("Raw runtime dir: {:?}", runtime_dir);
    }
}

```
Tokens:
Raw