Crate app_path

app-path

Create portable applications that keep files together with the executable.

Quick Start

use app_path::app_path;

// Files relative to your executable - not current directory!
let config = app_path!("config.toml");        // → /path/to/exe/config.toml
let database = app_path!("data/users.db");    // → /path/to/exe/data/users.db

// Environment overrides for deployment
let logs = app_path!("logs/app.log", env = "LOG_PATH");
// → Uses LOG_PATH if set, otherwise /path/to/exe/logs/app.log

// Works like standard paths - all Path methods available
if config.exists() {
    let content = std::fs::read_to_string(&config)?;
}

// Directory creation
logs.create_parents()?;                 // Creates logs/ directory for the file
app_path!("cache").create_dir()?;       // Creates cache/ directory itself

Key Features

• Portable: Relative paths resolve to executable directory
• System integration: Absolute paths work as-is
• Zero dependencies: Only standard library
• High performance: Static caching, minimal allocations
• Thread-safe: Concurrent access safe
• Zero-cost: All Path methods available via Deref (e.g., exists(), is_file(), extension())

API Design

• AppPath::new() - Recommended: Simple constructor (panics on failure)
• AppPath::try_new() - Libraries: Fallible version for error handling
• AppPath::with_override() - Deployment: Environment-configurable paths
• AppPath::with_override_fn() - Advanced: Function-based override logic
• app_path! - Macro: Convenient syntax with optional environment overrides
• try_app_path! - Macro (Fallible): Returns Result for explicit error handling
• AppPath::create_parents() - Files: Creates parent directories for files
• AppPath::create_dir() - Directories: Creates directories (and parents)
• exe_dir() - Advanced: Direct access to executable directory (panics on failure)
• try_exe_dir() - Libraries: Fallible executable directory access

Function Variants

This crate provides both panicking and fallible variants for most operations:

Panicking (Recommended)	Fallible (Libraries)	Use Case
AppPath::new()	AppPath::try_new()	Constructor methods
app_path!	try_app_path!	Convenient macros
exe_dir()	try_exe_dir()	Direct directory access

Macro Syntax Variants

Both app_path! and try_app_path! macros support four syntax forms for maximum flexibility:

// 1. Direct value
let config = app_path!("config.toml");
// → /path/to/exe/config.toml

// 2. With environment override
let config = app_path!("config.toml", env = "CONFIG_PATH");
// → Uses CONFIG_PATH if set, otherwise /path/to/exe/config.toml

// 3. With optional override value
let config = app_path!("config.toml", override = std::env::var("CONFIG_PATH").ok());
// → Uses CONFIG_PATH if available, otherwise /path/to/exe/config.toml

// 4. With function-based override
let config = app_path!("config.toml", fn = || {
    std::env::var("CONFIG_PATH").ok()
});
// → Uses function result if Some, otherwise /path/to/exe/config.toml

Variable Capturing

Both macros support variable capturing in complex expressions:

let version = "1.0";
let cache = app_path!(format!("cache-{version}")); // Captures `version`
// → /path/to/exe/cache-1.0

// Useful in closures and async blocks
async fn process_data(id: u32) {
    let output = app_path!(format!("output-{id}.json")); // Captures `id`
    // → /path/to/exe/output-123.json (where id = 123)
    // ... async processing
}

Panic Conditions

AppPath::new() and exe_dir() panic only if executable location cannot be determined:

• std::env::current_exe() fails (extremely rare system failure)
• Executable path is empty (indicates system corruption)

These represent unrecoverable system failures that occur at application startup. After the first successful call, the executable directory is cached and subsequent calls never panic.

For libraries or applications requiring graceful error handling, use the fallible variants AppPath::try_new() and try_exe_dir() instead.

Ecosystem Integration

app-path integrates seamlessly with popular Rust path crates through standard trait implementations:

UTF-8 Path Serialization (camino)

use app_path::app_path;
use camino::Utf8PathBuf;

let static_dir = app_path!("web/static", env = "STATIC_DIR");
let utf8_static = Utf8PathBuf::try_from(static_dir)?; // Direct conversion

// Safe JSON serialization with UTF-8 guarantees
let config = serde_json::json!({ "static_files": utf8_static });

Cross-Platform Path Types (typed-path)

use app_path::app_path;
use typed_path::{WindowsPath, UnixPath};

let dist_dir = app_path!("dist");

// Platform-specific paths with proper separators
let win_path = WindowsPath::new(&dist_dir);  // Uses \ on Windows  
let unix_path = UnixPath::new(&dist_dir);    // Uses / on Unix

Macros

app_path

Convenience macro for creating AppPath instances with optional environment variable overrides.

try_app_path

Fallible version of app_path! that returns a Result instead of panicking.

Structs

AppPath

Creates paths relative to the executable location for portable applications.

Enums

AppPathError

Error type for AppPath operations.

Functions

exe_dir

Get the executable’s directory.

try_exe_dir

Get the executable’s directory (fallible).