anil.recoil.org
XDG library path support for OCaml via Eio capabilities
linux
macos
ocaml
xdg
README
+75
README.md
+75
README.md
···
1
+
# xdge - XDG Base Directory Specification for Eio
2
+
3
+
This library implements the [XDG Base Directory
4
+
Specification](https://specifications.freedesktop.org/basedir-spec/latest/) for
5
+
OCaml applications using the [Eio](https://github.com/ocaml-multicore/eio)
6
+
effects-based I/O library.
7
+
8
+
## What is XDG?
9
+
10
+
The 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
+
18
+
The 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
+
24
+
Eio uses a **capability-based** approach to I/O where filesystem access must be
25
+
explicitly passed to functions. This design aligns naturally with XDG directory
26
+
management. For example:
27
+
28
+
```ocaml
29
+
(* Filesystem access is an explicit capability *)
30
+
let xdg = Xdge.create env#fs "myapp"
31
+
```
32
+
33
+
The capability model provides the benefit that code that needs filesystem
34
+
access must receive the `fs` capability, with no hidden global state or ambient
35
+
authority. The `Eio.Path.t` type returned by xdge encapsulates both the
36
+
filesystem capability and the path, preventing path traversal outside the
37
+
granted capability. Applications can restrict filesystem access by passing a
38
+
sandboxed `fs` capability, and xdge respects those boundaries.
39
+
40
+
## Usage
41
+
42
+
```ocaml
43
+
Eio_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
+
56
+
For CLI applications, xdge provides Cmdliner terms that handle environment
57
+
variable precedence and command-line overrides:
58
+
59
+
```ocaml
60
+
let () =
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
+
```
70
+
opam install xdge
71
+
```
72
+
73
+
## License
74
+
75
+
ISC