XDG library path support for OCaml via Eio capabilities
anil.recoil.org
linux
macos
ocaml
xdg
1# xdge - XDG Base Directory Specification for Eio
2
3This library implements the [XDG Base Directory
4Specification](https://specifications.freedesktop.org/basedir-spec/latest/) for
5OCaml applications using the [Eio](https://github.com/ocaml-multicore/eio)
6effects-based I/O library.
7
8## What is XDG?
9
10The XDG Base Directory Specification defines standard locations for user-specific files on Unix-like systems, keeping home directories clean and organized:
11
12- Config (`~/.config/app`): User preferences and settings
13- Data (`~/.local/share/app`): Persistent application data
14- Cache (`~/.cache/app`): Non-essential cached data (safe to delete)
15- State (`~/.local/state/app`): Logs, history, and runtime state
16- Runtime (`$XDG_RUNTIME_DIR/app`): Sockets, pipes, and session-bound files
17
18The specification also defines system-wide search paths (`/etc/xdg`,
19`/usr/share`) and a precedence system using environment variables
20(`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and so on).
21
22## Why Eio?
23
24Eio uses a **capability-based** approach to I/O where filesystem access must be
25explicitly passed to functions. This design aligns naturally with XDG directory
26management. For example:
27
28```ocaml
29(* Filesystem access is an explicit capability *)
30let xdg = Xdge.create env#fs "myapp"
31```
32
33The capability model provides the benefit that code that needs filesystem
34access must receive the `fs` capability, with no hidden global state or ambient
35authority. The `Eio.Path.t` type returned by xdge encapsulates both the
36filesystem capability and the path, preventing path traversal outside the
37granted capability. Applications can restrict filesystem access by passing a
38sandboxed `fs` capability, and xdge respects those boundaries.
39
40## Usage
41
42```ocaml
43Eio_main.run @@ fun env ->
44 let xdg = Xdge.create env#fs "myapp" in
45
46 (* Access XDG directories as Eio paths *)
47 let config = Xdge.config_dir xdg in
48 let data = Xdge.data_dir xdg in
49
50 (* Search for files following XDG precedence *)
51 match Xdge.find_config_file xdg "settings.json" with
52 | Some path -> (* use path *)
53 | None -> (* use defaults *)
54```
55
56For CLI applications, xdge provides Cmdliner terms that handle environment
57variable precedence and command-line overrides:
58
59```ocaml
60let () =
61 Eio_main.run @@ fun env ->
62 let term = Xdge.Cmd.term "myapp" env#fs () in
63 (* Generates --config-dir, --data-dir, etc. flags *)
64 (* Respects MYAPP_CONFIG_DIR > XDG_CONFIG_HOME > default *)
65```
66
67## Installation
68
69```
70opam install xdge
71```
72
73## License
74
75ISC