nox-xdg #

XDG Base Directory specification: pure path resolution.

nox-xdg is a fork of dune's internal xdg library (META description: "[Internal] XDG base directories specification implementation"). Forked rather than depended on so this package has no upstream dep on a build-tool internal — dune doesn't promise to keep its xdg library stable across releases.

The OCaml symbol exported by the C stub is renamed from dune_xdg__get_known_folder_path to nox_xdg__get_known_folder_path to avoid duplicate-symbol errors at link time when a downstream binary pulls in both this package and dune's internal xdg library.

What it does #

Computes the standard XDG base directory paths from the XDG Base Directory Specification on Unix, and the corresponding Windows known folders on Windows. Pure: no filesystem effects, no Eio dependency.

For an Eio-aware wrapper that creates directories, validates permissions, and threads paths through Eio capabilities, see nox-xdge.

Installation #

$ opam install nox-xdg

Usage #

let dirs = Xdg.create ~env:Sys.getenv_opt ()

let config_path =
  Filename.concat (Xdg.config_dir dirs) "myapp/settings.json"

let cache_path =
  Filename.concat (Xdg.cache_dir dirs) "myapp/thumbnails"

The defaults follow the spec:

Function	Env override	Unix default
`Xdg.config_dir`	`$XDG_CONFIG_HOME`	`$HOME/.config`
`Xdg.data_dir`	`$XDG_DATA_HOME`	`$HOME/.local/share`
`Xdg.cache_dir`	`$XDG_CACHE_HOME`	`$HOME/.cache`
`Xdg.state_dir`	`$XDG_STATE_HOME`	`$HOME/.local/state`
`Xdg.runtime_dir`	`$XDG_RUNTIME_DIR`	(none — returns `None`)

Per spec §4, env var values must be absolute; relative or empty values are ignored and the default is used instead.

Testing #

Pass a closure for ~env to inject a deterministic environment:

let test_env =
  let bindings =
    [ "HOME", "/home/test"; "XDG_CONFIG_HOME", "/etc/xdg" ]
  in
  fun name -> List.assoc_opt name bindings

let dirs = Xdg.create ~env:test_env ()
let _ = assert (Xdg.config_dir dirs = "/etc/xdg")

Windows #

On Windows, defaults come from SHGetKnownFolderPath (FOLDERID_LocalAppData for config/data/state, FOLDERID_InternetCache for cache) instead of the Unix $HOME/.config paths. Override with ~win32:bool if you need to force a particular platform behaviour in tests.

Licence #

MIT. Original code by Jane Street; this fork by Thomas Gazagnaire. See LICENSE.md.

Clone this repository