Reference

std/os/directories

std/os/src/directories.trb

Directories: where a user's files belong by the convention of the system - the home directory, and the bases for configuration, data, state, cache and temporary files.

Windows answers from its Known Folders, Linux and FreeBSD from the XDG base directories, macOS from its Library.

type Directories

type Directories

Where a user's files belong, by the convention of the system. Each answers the base: an application joins its own name.

  • Linux and FreeBSD follow the XDG base directories: HOME (else the account entry), XDG_CONFIG_HOME (else ~/.config), XDG_DATA_HOME (else ~/.local/share), XDG_STATE_HOME (else ~/.local/state), XDG_CACHE_HOME (else ~/.cache), and TMPDIR (else /tmp).
  • Windows answers its Known Folders: FOLDERID_Profile, FOLDERID_RoamingAppData for configuration and data, FOLDERID_LocalAppData for state and cache, and GetTempPath2W.
  • macOS answers HOME (else the account entry), ~/Library/Application Support for configuration, data and state, ~/Library/Caches, and TMPDIR (else the user's own temporary directory).

Examples

const configuration = Directories.configuration()?
const settings = configuration.joined Path.from("torb")
print settings

Pitfalls

  • An XDG variable that holds a relative path is ignored, as the XDG specification requires: XDG_CACHE_HOME=cache answers ~/.cache.

fn home

static fn home(): Result<Path, OsError>

The user's home directory.

fn configuration

static fn configuration(): Result<Path, OsError>

Where an application keeps what the user configured.

fn data

static fn data(): Result<Path, OsError>

Where an application keeps what it made for the user and that is worth keeping.

fn state

static fn state(): Result<Path, OsError>

Where an application keeps what should survive a restart but is no document: histories, logs, the last layout.

fn cache

static fn cache(): Result<Path, OsError>

Where an application keeps what it can make again, and what may be deleted at any time.

fn temporary

static fn temporary(): Path

The directory for temporary files. Always answers: every system has one, and /tmp is the last resort.