From c5fda432ed85c19e3d4a2a8528a12478bd76d76a Mon Sep 17 00:00:00 2001 From: Aaron Allen Date: Sun, 10 Aug 2025 00:02:06 -0500 Subject: [PATCH] Update README and docs for 0.2.0 breaking changes - Update README to reflect the removal of deprecated `*_dir()` methods and the transition to `Option` return types. - Add migration guide to help users upgrade from 0.1.x to 0.2.0. - Document dependency removals (`libc`, `eyre`) and simplified error handling. - Highlight `runtime()` fallback behavior changes for Linux. - Ensure consistency in examples and method descriptions across all documentation. --- CHANGELOG.md | 21 +++++---- README.md | 63 ++++++++++++++++++--------- docs/migration_guides/0.1.x-0.2.0.md | 64 +++++++++++++++++----------- 3 files changed, 96 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8da56df..d228cf3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,26 +10,29 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve * **BREAKING**: All methods now return `Option` instead of `Result` * **BREAKING**: `home()` method now uses `std::env::home_dir()` directly (was previously deprecated, now undeprecated) +* **BREAKING**: `runtime()` method on Linux now uses `$TMPDIR` then `/tmp` fallback instead of `/run/user/{uid}` * Simplified error handling by removing `eyre` dependency from public API * Updated documentation and examples to use Option pattern matching ### Removed * **BREAKING**: Removed `eyre` dependency from public API +* **BREAKING**: Removed `libc` dependency entirely * **BREAKING**: Removed all deprecated `*_dir()` method variants: -* `desktop_dir()` (use `desktop()`) -* `documents_dir()` (use `documents()`) -* `download_dir()` (use `downloads()`) -* `music_dir()` (use `music()`) -* `pictures_dir()` (use `pictures()`) -* `publicshare_dir()` (use `publicshare()`) -* `runtime_dir()` (use `runtime()`) -* `templates_dir()` (use `templates()`) -* `videos_dir()` (use `videos()`) + * `desktop_dir()` (use `desktop()`) + * `documents_dir()` (use `documents()`) + * `download_dir()` (use `downloads()`) + * `music_dir()` (use `music()`) + * `pictures_dir()` (use `pictures()`) + * `publicshare_dir()` (use `publicshare()`) + * `runtime_dir()` (use `runtime()`) + * `templates_dir()` (use `templates()`) + * `videos_dir()` (use `videos()`) ### Fixed * Eliminated potential panic in `home()` method by properly handling `None` case from `std::env::home_dir()` +* Removed unsafe code by eliminating libc dependency ## [0.1.0] - 2025-08-08 diff --git a/README.md b/README.md index b8e556b..617e783 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ across all platforms while providing sensible platform-specific fallbacks. - **XDG-first approach**: Respects XDG environment variables on all platforms - **Platform-aware fallbacks**: Uses native conventions when XDG variables aren't set - **Cross-platform**: Works on Linux, macOS, and Windows -- **Minimal dependencies**: Only uses `libc` for Unix systems +- **Zero dependencies**: Only uses `std` library - **Type-safe**: Returns `Option` for simple error handling ## Usage @@ -50,23 +50,23 @@ fn main() { ## Supported Directories -| Method | XDG Variable | Linux Default | macOS Default | Windows Default | -|-----------------|------------------------|------------------|---------------------------------|----------------------------| -| `bin_home()` | `XDG_BIN_HOME` | `~/.local/bin` | `~/.local/bin` | `%LOCALAPPDATA%\Programs` | -| `cache_home()` | `XDG_CACHE_HOME` | `~/.cache` | `~/Library/Caches` | `%LOCALAPPDATA%` | -| `config_home()` | `XDG_CONFIG_HOME` | `~/.config` | `~/Library/Application Support` | `%APPDATA%` | -| `data_home()` | `XDG_DATA_HOME` | `~/.local/share` | `~/Library/Application Support` | `%APPDATA%` | -| `desktop()` | `XDG_DESKTOP_DIR` | `~/Desktop` | `~/Desktop` | `%USERPROFILE%\Desktop` | -| `documents()` | `XDG_DOCUMENTS_DIR` | `~/Documents` | `~/Documents` | `%USERPROFILE%\Documents` | -| `downloads()` | `XDG_DOWNLOAD_DIR` | `~/Downloads` | `~/Downloads` | `%USERPROFILE%\Downloads` | -| `music()` | `XDG_MUSIC_DIR` | `~/Music` | `~/Music` | `%USERPROFILE%\Music` | -| `pictures()` | `XDG_PICTURES_DIR` | `~/Pictures` | `~/Pictures` | `%USERPROFILE%\Pictures` | -| `publicshare()` | `XDG_PUBLICSHARE_DIR` | `~/Public` | `~/Public` | `C:\Users\Public` | -| `runtime()` | `XDG_RUNTIME_DIR` | `/run/user/$UID` | `$TMPDIR` or `/tmp` | `%TEMP%` | -| `state_home()` | `XDG_STATE_HOME` | `~/.local/state` | `~/Library/Application Support` | `%LOCALAPPDATA%` | -| `templates()` | `XDG_TEMPLATES_DIR` | `~/Templates` | `~/Templates` | `%USERPROFILE%\Templates` | -| `videos()` | `XDG_VIDEOS_DIR` | `~/Videos` | `~/Movies` | `%USERPROFILE%\Videos` | -| `home()` | `HOME` / `USERPROFILE` | `$HOME` | `$HOME` | `%USERPROFILE%` | +| Method | XDG Variable | Linux Default | macOS Default | Windows Default | +|-----------------|------------------------|----------------------|----------------------------------|-----------------------------| +| `bin_home()` | `XDG_BIN_HOME` | `~/.local/bin` | `~/.local/bin` | `%LOCALAPPDATA%\Programs` | +| `cache_home()` | `XDG_CACHE_HOME` | `~/.cache` | `~/Library/Caches` | `%LOCALAPPDATA%` | +| `config_home()` | `XDG_CONFIG_HOME` | `~/.config` | `~/Library/Application Support` | `%APPDATA%` | +| `data_home()` | `XDG_DATA_HOME` | `~/.local/share` | `~/Library/Application Support` | `%APPDATA%` | +| `desktop()` | `XDG_DESKTOP_DIR` | `~/Desktop` | `~/Desktop` | `%USERPROFILE%\Desktop` | +| `documents()` | `XDG_DOCUMENTS_DIR` | `~/Documents` | `~/Documents` | `%USERPROFILE%\Documents` | +| `downloads()` | `XDG_DOWNLOAD_DIR` | `~/Downloads` | `~/Downloads` | `%USERPROFILE%\Downloads` | +| `music()` | `XDG_MUSIC_DIR` | `~/Music` | `~/Music` | `%USERPROFILE%\Music` | +| `pictures()` | `XDG_PICTURES_DIR` | `~/Pictures` | `~/Pictures` | `%USERPROFILE%\Pictures` | +| `publicshare()` | `XDG_PUBLICSHARE_DIR` | `~/Public` | `~/Public` | `C:\Users\Public` | +| `runtime()` | `XDG_RUNTIME_DIR` | `$TMPDIR` or `/tmp` | `$TMPDIR` or `/tmp` | `%TEMP%` | +| `state_home()` | `XDG_STATE_HOME` | `~/.local/state` | `~/Library/Application Support` | `%LOCALAPPDATA%` | +| `templates()` | `XDG_TEMPLATES_DIR` | `~/Templates` | `~/Templates` | `%USERPROFILE%\Templates` | +| `videos()` | `XDG_VIDEOS_DIR` | `~/Videos` | `~/Movies` | `%USERPROFILE%\Videos` | +| `home()` | `HOME` / `USERPROFILE` | `$HOME` | `$HOME` | `%USERPROFILE%` | ## XDG Environment Variable Priority @@ -125,9 +125,34 @@ let config_dir = Dir::config_home().unwrap_or_else(|| { }); ``` +## Migration from 0.1.x + +Version 0.2.0 introduces breaking changes: + +- **Return type changed**: Methods now return `Option` instead of `Result` +- **Removed deprecated methods**: All `*_dir()` variants have been removed +- **No more eyre dependency**: Simpler error handling with Options + +Migration guide: + +```rust +// 0.1.x +let config = Dir::config_home()?; +let desktop = Dir::desktop_dir()?; + +// 0.2.x +let config = Dir::config_home().ok_or("Failed to get config dir")?; +let desktop = Dir::desktop().ok_or("Failed to get desktop dir")?; + +// Or using if-let +if let Some(config) = Dir::config_home() { + // use config +} +``` + ## Dependencies -- `libc`: For Unix systems (accessing user database when `$HOME` isn't set) +None! This crate only uses Rust's standard library. ## License diff --git a/docs/migration_guides/0.1.x-0.2.0.md b/docs/migration_guides/0.1.x-0.2.0.md index 70562c7..7df2842 100644 --- a/docs/migration_guides/0.1.x-0.2.0.md +++ b/docs/migration_guides/0.1.x-0.2.0.md @@ -7,8 +7,9 @@ This guide covers all breaking changes and provides step-by-step migration instr 1. **Return type changed**: All methods now return `Option` instead of `Result` 2. **Removed deprecated methods**: All `*_dir()` variants have been removed -3. **Removed eyre dependency**: No longer uses `eyre::Error` for error handling +3. **Removed dependencies**: No longer uses `eyre` or `libc` dependencies 4. **Simplified error handling**: Use Option pattern matching instead of Result +5. **Runtime directory behavior changed**: Linux now uses `$TMPDIR` then `/tmp` fallback instead of `/run/user/{uid}` ## Dependency Changes @@ -18,6 +19,7 @@ This guide covers all breaking changes and provides step-by-step migration instr [dependencies] dir_spec = "0.1.0" eyre = "0.6" # Required for error handling +libc = "1.0" # Used internally by dir_spec ``` ### After (0.2.0) @@ -25,32 +27,32 @@ eyre = "0.6" # Required for error handling ```toml [dependencies] dir_spec = "0.2.0" -# eyre no longer required +# No additional dependencies required - zero dependency crate! ``` ## Method Signature Changes All public methods have changed their return type: -| Method | 0.1.x Return Type | 0.2.0 Return Type | -|--------------|--------------------|--------------------| -| All methods | `Result` | `Option` | +| Method | 0.1.x Return Type | 0.2.0 Return Type | +|--------------|-------------------|-------------------| +| All methods | `Result` | `Option` | ## Removed Methods The following deprecated methods have been removed completely: -| Removed Method | Replacement | -|---------------------|-----------------| -| `desktop_dir()` | `desktop()` | -| `documents_dir()` | `documents()` | -| `download_dir()` | `downloads()` | -| `music_dir()` | `music()` | -| `pictures_dir()` | `pictures()` | -| `publicshare_dir()` | `publicshare()` | -| `runtime_dir()` | `runtime()` | -| `templates_dir()` | `templates()` | -| `videos_dir()` | `videos()` | +| Removed Method | Replacement | +|---------------------|------------------| +| `desktop_dir()` | `desktop()` | +| `documents_dir()` | `documents()` | +| `download_dir()` | `downloads()` | +| `music_dir()` | `music()` | +| `pictures_dir()` | `pictures()` | +| `publicshare_dir()` | `publicshare()` | +| `runtime_dir()` | `runtime()` | +| `templates_dir()` | `templates()` | +| `videos_dir()` | `videos()` | ## Migration Patterns @@ -203,9 +205,23 @@ fn setup_directories() -> Result<(), Box> { } ``` -## Deprecated Method Migration +## Platform-Specific Behavior Changes -### Simple Replacements +### Runtime Directory Changes on Linux + +**Before (0.1.x):** + +- Linux used `/run/user/{uid}` (required unsafe `libc` calls to get UID) + +**After (0.2.0):** + +- Linux now uses `$TMPDIR` environment variable, falling back to `/tmp` +- Unified behavior with macOS (both platforms now use the same logic) +- No more unsafe code or external dependencies + +This change affects the `runtime()` method fallback behavior when `XDG_RUNTIME_DIR` is not set. + +## Deprecated Method Migration **Before (0.1.x):** @@ -240,9 +256,9 @@ let templates = Dir::templates().ok_or("No templates directory")?; let videos = Dir::videos().ok_or("No videos directory")?; ``` -## Error Handling Strategy Changes +### Simple Replacements -### Custom Error Types +## Error Handling Strategy Changes If you need more specific error information, you can create custom error types: @@ -276,7 +292,7 @@ fn get_config_dir() -> Result { } ``` -### Bulk Directory Resolution +### Custom Error Types For applications that need multiple directories and want to fail fast: @@ -303,7 +319,7 @@ match get_app_directories() { } ``` -## Testing Changes +### Bulk Directory Resolution Update your tests to handle the new return type: @@ -343,7 +359,7 @@ mod tests { } ``` -## Common Gotchas +## Testing Changes ### 1. Forgetting to Handle None Cases @@ -412,7 +428,7 @@ fn get_dirs() -> Result, Box> { } ``` -## Benefits of the Migration +## Common Gotchas After migrating to 0.2.0, you'll benefit from: -- 2.51.2