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. The folders a user looks at - documents, downloads, desktop, pictures, music and videos - are the same question answered by the system's own convention for them.

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). The user folders are the XDG_DOCUMENTS_DIR and its siblings in user-dirs.dirs of the configuration directory, else ~/Documents, ~/Downloads, ~/Desktop, ~/Pictures, ~/Music and ~/Videos.
  • Windows answers its Known Folders: FOLDERID_Profile, FOLDERID_RoamingAppData for configuration and data, FOLDERID_LocalAppData for state and cache, GetTempPath2W, and FOLDERID_Documents, FOLDERID_Downloads, FOLDERID_Desktop, FOLDERID_Pictures, FOLDERID_Music and FOLDERID_Videos for the user folders.
  • macOS answers HOME (else the account entry), ~/Library/Application Support for configuration, data and state, ~/Library/Caches, TMPDIR (else the user's own temporary directory), and ~/Documents, ~/Downloads, ~/Desktop, ~/Pictures, ~/Music and ~/Movies for the user folders.
  • A browser has no user, so everything but the temporary directory, /tmp of its file system in memory, is Unsupported.

Examples

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

const downloads = Directories.downloads()?
print downloads

Pitfalls

  • An XDG variable that holds a relative path is ignored, as the XDG specification requires: XDG_CACHE_HOME=cache answers ~/.cache.
  • A user folder answers a path whether or not it exists: the fallback below the home is not checked, so create the folder before writing to it.
  • A folder the user disabled - XDG_MUSIC_DIR="$HOME/" in user-dirs.dirs - answers the fallback, never the home directory itself.

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 documents

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

Where the user keeps documents.

fn downloads

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

Where downloads land.

fn desktop

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

The folder the desktop shows.

fn pictures

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

Where the user keeps pictures.

fn music

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

Where the user keeps music.

fn videos

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

Where the user keeps videos: ~/Movies on macOS.

fn temporary

static fn temporary(): Path

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