-17

xdge/.gitignore

reviewed

··· 1 1 - # OCaml build artifacts 2 2 - _build/ 3 3 - *.install 4 4 - *.merlin 5 5 - 6 6 - # Third-party sources (fetch locally with opam source) 7 7 - third_party/ 8 8 - 9 9 - # Editor and OS files 10 10 - .DS_Store 11 11 - *.swp 12 12 - *~ 13 13 - .vscode/ 14 14 - .idea/ 15 15 - 16 16 - # Opam local switch 17 17 - _opam/

-1

xdge/.ocamlformat

reviewed

··· 1 1 - version=0.28.1

-49

xdge/.tangled/workflows/build.yml

reviewed

··· 1 1 - when: 2 2 - - event: ["push", "pull_request"] 3 3 - branch: ["main"] 4 4 - 5 5 - engine: nixery 6 6 - 7 7 - dependencies: 8 8 - nixpkgs: 9 9 - - shell 10 10 - - stdenv 11 11 - - findutils 12 12 - - binutils 13 13 - - libunwind 14 14 - - ncurses 15 15 - - opam 16 16 - - git 17 17 - - gawk 18 18 - - gnupatch 19 19 - - gnum4 20 20 - - gnumake 21 21 - - gnutar 22 22 - - gnused 23 23 - - gnugrep 24 24 - - diffutils 25 25 - - gzip 26 26 - - bzip2 27 27 - - gcc 28 28 - - ocaml 29 29 - 30 30 - steps: 31 31 - - name: opam 32 32 - command: | 33 33 - opam init --disable-sandboxing -any 34 34 - - name: switch 35 35 - command: | 36 36 - opam install . --confirm-level=unsafe-yes --deps-only 37 37 - - name: build 38 38 - command: | 39 39 - opam exec -- dune build 40 40 - - name: switch-test 41 41 - command: | 42 42 - opam install . --confirm-level=unsafe-yes --deps-only --with-test 43 43 - - name: test 44 44 - command: | 45 45 - opam exec -- dune runtest --verbose 46 46 - - name: doc 47 47 - command: | 48 48 - opam install -y odoc 49 49 - opam exec -- dune build @doc

-10

xdge/CHANGES.md

reviewed

··· 1 1 - v1.1.0 (dev) 2 2 - ------------ 3 3 - 4 4 - - Remove dependency on `eio_main` for library (@avsm). 5 5 - Thanks to @Alizter for the workaround in https://github.com/ocaml/dune/issues/12821). 6 6 - 7 7 - v1.0.0 (2025-11-29) 8 8 - ------------------- 9 9 - 10 10 - - Initial public release (@avsm)

-18

xdge/LICENSE.md

reviewed

··· 1 1 - (* 2 2 - * ISC License 3 3 - * 4 4 - * Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org> 5 5 - * 6 6 - * Permission to use, copy, modify, and distribute this software for any 7 7 - * purpose with or without fee is hereby granted, provided that the above 8 8 - * copyright notice and this permission notice appear in all copies. 9 9 - * 10 10 - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11 11 - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12 12 - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13 13 - * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14 14 - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15 15 - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16 16 - * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17 17 - * 18 18 - *)

-75

xdge/README.md

reviewed

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

-4

xdge/dune

reviewed

··· 1 1 - (alias 2 2 - (name default) 3 3 - (deps 4 4 - (alias_rec lib/all)))

-31

xdge/dune-project

reviewed

··· 1 1 - (lang dune 3.20) 2 2 - 3 3 - (name xdge) 4 4 - 5 5 - (generate_opam_files true) 6 6 - 7 7 - (license ISC) 8 8 - (authors "Anil Madhavapeddy") 9 9 - (homepage "https://tangled.sh/@anil.recoil.org/xdge") 10 10 - (maintainers "Anil Madhavapeddy <anil@recoil.org>") 11 11 - (bug_reports "https://tangled.sh/@anil.recoil.org/xdge/issues") 12 12 - (maintenance_intent "(latest)") 13 13 - 14 14 - (package 15 15 - (name xdge) 16 16 - (synopsis "XDG Base Directory Specification support for Eio") 17 17 - (description 18 18 - "This library implements the XDG Base Directory Specification \ 19 19 - with Eio capabilities to provide safe access to configuration, \ 20 20 - data, cache, state, and runtime directories. The library exposes \ 21 21 - Cmdliner terms that allow for proper environment variable overrides \ 22 22 - and command-line flags.") 23 23 - (depends 24 24 - (ocaml (>= 5.1.0)) 25 25 - (eio (>= 1.1)) 26 26 - (cmdliner (>= 1.2.0)) 27 27 - fmt 28 28 - xdg 29 29 - (eio_main :with-test) 30 30 - (odoc :with-doc) 31 31 - (alcotest (and :with-test (>= 1.7.0)))))

-4

xdge/lib/dune

reviewed

··· 1 1 - (library 2 2 - (public_name xdge) 3 3 - (name xdge) 4 4 - (libraries eio xdg unix cmdliner fmt))

-668

xdge/lib/xdge.ml

reviewed

··· 1 1 - (*--------------------------------------------------------------------------- 2 2 - Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved. 3 3 - SPDX-License-Identifier: ISC 4 4 - ---------------------------------------------------------------------------*) 5 5 - 6 6 - type source = Default | Env of string | Cmdline 7 7 - 8 8 - type t = { 9 9 - app_name : string; 10 10 - config_dir : Eio.Fs.dir_ty Eio.Path.t; 11 11 - config_dir_source : source; 12 12 - data_dir : Eio.Fs.dir_ty Eio.Path.t; 13 13 - data_dir_source : source; 14 14 - cache_dir : Eio.Fs.dir_ty Eio.Path.t; 15 15 - cache_dir_source : source; 16 16 - state_dir : Eio.Fs.dir_ty Eio.Path.t; 17 17 - state_dir_source : source; 18 18 - runtime_dir : Eio.Fs.dir_ty Eio.Path.t option; 19 19 - runtime_dir_source : source; 20 20 - config_dirs : Eio.Fs.dir_ty Eio.Path.t list; 21 21 - data_dirs : Eio.Fs.dir_ty Eio.Path.t list; 22 22 - } 23 23 - 24 24 - let ensure_dir ?(perm = 0o755) path = Eio.Path.mkdirs ~exists_ok:true ~perm path 25 25 - 26 26 - let validate_runtime_base_dir base_path = 27 27 - (* Validate the base XDG_RUNTIME_DIR has correct permissions per spec *) 28 28 - try 29 29 - let path_str = Eio.Path.native_exn base_path in 30 30 - let stat = Eio.Path.stat ~follow:true base_path in 31 31 - let current_perm = stat.perm land 0o777 in 32 32 - if current_perm <> 0o700 then 33 33 - failwith 34 34 - (Printf.sprintf 35 35 - "XDG_RUNTIME_DIR base directory %s has incorrect permissions: %o \ 36 36 - (must be 0700)" 37 37 - path_str current_perm); 38 38 - (* Check ownership - directory should be owned by current user *) 39 39 - let uid = Unix.getuid () in 40 40 - if stat.uid <> Int64.of_int uid then 41 41 - failwith 42 42 - (Printf.sprintf 43 43 - "XDG_RUNTIME_DIR base directory %s not owned by current user (uid \ 44 44 - %d, owner %Ld)" 45 45 - path_str uid stat.uid) 46 46 - (* TODO: Check that directory is on local filesystem (not networked). 47 47 - This would require filesystem type detection which is OS-specific. *) 48 48 - with exn -> 49 49 - failwith 50 50 - (Printf.sprintf "Cannot validate XDG_RUNTIME_DIR: %s" 51 51 - (Printexc.to_string exn)) 52 52 - 53 53 - let ensure_runtime_dir _fs app_runtime_path = 54 54 - (* Base directory validation is done in resolve_runtime_dir, 55 55 - so we just create the app subdirectory *) 56 56 - ensure_dir app_runtime_path 57 57 - 58 58 - let get_home_dir fs = 59 59 - let home_str = 60 60 - match Sys.getenv_opt "HOME" with 61 61 - | Some home -> home 62 62 - | None -> ( 63 63 - match Sys.os_type with 64 64 - | "Win32" | "Cygwin" -> ( 65 65 - match Sys.getenv_opt "USERPROFILE" with 66 66 - | Some profile -> profile 67 67 - | None -> failwith "Cannot determine home directory") 68 68 - | _ -> ( 69 69 - try Unix.((getpwuid (getuid ())).pw_dir) 70 70 - with _ -> failwith "Cannot determine home directory")) 71 71 - in 72 72 - Eio.Path.(fs / home_str) 73 73 - 74 74 - let make_env_var_name app_name suffix = 75 75 - String.uppercase_ascii app_name ^ "_" ^ suffix 76 76 - 77 77 - exception Invalid_xdg_path of string 78 78 - 79 79 - let validate_absolute_path context path = 80 80 - if Filename.is_relative path then 81 81 - raise 82 82 - (Invalid_xdg_path 83 83 - (Printf.sprintf "%s must be an absolute path, got: %s" context path)) 84 84 - 85 85 - let resolve_path fs home_path base_path = 86 86 - if Filename.is_relative base_path then Eio.Path.(home_path / base_path) 87 87 - else Eio.Path.(fs / base_path) 88 88 - 89 89 - (* Helper to resolve system directories (config_dirs or data_dirs) *) 90 90 - let resolve_system_dirs fs home_path app_name override_suffix xdg_var 91 91 - default_paths = 92 92 - let override_var = make_env_var_name app_name override_suffix in 93 93 - match Sys.getenv_opt override_var with 94 94 - | Some dirs when dirs <> "" -> 95 95 - String.split_on_char ':' dirs 96 96 - |> List.filter (fun s -> s <> "") 97 97 - |> List.filter_map (fun path -> 98 98 - try 99 99 - validate_absolute_path override_var path; 100 100 - Some Eio.Path.(resolve_path fs home_path path / app_name) 101 101 - with Invalid_xdg_path _ -> None) 102 102 - | Some _ | None -> ( 103 103 - match Sys.getenv_opt xdg_var with 104 104 - | Some dirs when dirs <> "" -> 105 105 - String.split_on_char ':' dirs 106 106 - |> List.filter (fun s -> s <> "") 107 107 - |> List.filter_map (fun path -> 108 108 - try 109 109 - validate_absolute_path xdg_var path; 110 110 - Some Eio.Path.(resolve_path fs home_path path / app_name) 111 111 - with Invalid_xdg_path _ -> None) 112 112 - | Some _ | None -> 113 113 - List.map 114 114 - (fun path -> Eio.Path.(resolve_path fs home_path path / app_name)) 115 115 - default_paths) 116 116 - 117 117 - (* Helper to resolve a user directory with override precedence *) 118 118 - let resolve_user_dir fs home_path app_name xdg_ctx xdg_getter override_suffix = 119 119 - let override_var = make_env_var_name app_name override_suffix in 120 120 - match Sys.getenv_opt override_var with 121 121 - | Some dir when dir <> "" -> 122 122 - validate_absolute_path override_var dir; 123 123 - (Eio.Path.(fs / dir / app_name), Env override_var) 124 124 - | Some _ | None -> 125 125 - let xdg_base = xdg_getter xdg_ctx in 126 126 - let base_path = resolve_path fs home_path xdg_base in 127 127 - (Eio.Path.(base_path / app_name), Default) 128 128 - 129 129 - (* Helper to resolve runtime directory (special case since it can be None) *) 130 130 - let resolve_runtime_dir fs home_path app_name xdg_ctx = 131 131 - let override_var = make_env_var_name app_name "RUNTIME_DIR" in 132 132 - match Sys.getenv_opt override_var with 133 133 - | Some dir when dir <> "" -> 134 134 - validate_absolute_path override_var dir; 135 135 - (* Validate the base runtime directory has correct permissions *) 136 136 - let base_runtime_dir = resolve_path fs home_path dir in 137 137 - validate_runtime_base_dir base_runtime_dir; 138 138 - (Some Eio.Path.(base_runtime_dir / app_name), Env override_var) 139 139 - | Some _ | None -> 140 140 - ( (match Xdg.runtime_dir xdg_ctx with 141 141 - | Some base -> 142 142 - (* Validate the base runtime directory has correct permissions *) 143 143 - let base_runtime_dir = resolve_path fs home_path base in 144 144 - validate_runtime_base_dir base_runtime_dir; 145 145 - Some Eio.Path.(base_runtime_dir / app_name) 146 146 - | None -> None), 147 147 - Default ) 148 148 - 149 149 - let validate_standard_xdg_vars () = 150 150 - (* Validate standard XDG environment variables for absolute paths *) 151 151 - let xdg_vars = 152 152 - [ 153 153 - "XDG_CONFIG_HOME"; 154 154 - "XDG_DATA_HOME"; 155 155 - "XDG_CACHE_HOME"; 156 156 - "XDG_STATE_HOME"; 157 157 - "XDG_RUNTIME_DIR"; 158 158 - "XDG_CONFIG_DIRS"; 159 159 - "XDG_DATA_DIRS"; 160 160 - ] 161 161 - in 162 162 - List.iter 163 163 - (fun var -> 164 164 - match Sys.getenv_opt var with 165 165 - | Some value when value <> "" -> 166 166 - if String.contains value ':' then 167 167 - (* Colon-separated list - validate each part *) 168 168 - String.split_on_char ':' value 169 169 - |> List.filter (fun s -> s <> "") 170 170 - |> List.iter (fun path -> validate_absolute_path var path) 171 171 - else 172 172 - (* Single path *) 173 173 - validate_absolute_path var value 174 174 - | _ -> ()) 175 175 - xdg_vars 176 176 - 177 177 - let create fs app_name = 178 178 - let fs = fs in 179 179 - let home_path = get_home_dir fs in 180 180 - (* First validate all standard XDG environment variables *) 181 181 - validate_standard_xdg_vars (); 182 182 - let xdg_ctx = Xdg.create ~env:Sys.getenv_opt () in 183 183 - (* User directories *) 184 184 - let config_dir, config_dir_source = 185 185 - resolve_user_dir fs home_path app_name xdg_ctx Xdg.config_dir "CONFIG_DIR" 186 186 - in 187 187 - let data_dir, data_dir_source = 188 188 - resolve_user_dir fs home_path app_name xdg_ctx Xdg.data_dir "DATA_DIR" 189 189 - in 190 190 - let cache_dir, cache_dir_source = 191 191 - resolve_user_dir fs home_path app_name xdg_ctx Xdg.cache_dir "CACHE_DIR" 192 192 - in 193 193 - let state_dir, state_dir_source = 194 194 - resolve_user_dir fs home_path app_name xdg_ctx Xdg.state_dir "STATE_DIR" 195 195 - in 196 196 - (* Runtime directory *) 197 197 - let runtime_dir, runtime_dir_source = 198 198 - resolve_runtime_dir fs home_path app_name xdg_ctx 199 199 - in 200 200 - (* System directories *) 201 201 - let config_dirs = 202 202 - resolve_system_dirs fs home_path app_name "CONFIG_DIRS" "XDG_CONFIG_DIRS" 203 203 - [ "/etc/xdg" ] 204 204 - in 205 205 - let data_dirs = 206 206 - resolve_system_dirs fs home_path app_name "DATA_DIRS" "XDG_DATA_DIRS" 207 207 - [ "/usr/local/share"; "/usr/share" ] 208 208 - in 209 209 - ensure_dir config_dir; 210 210 - ensure_dir data_dir; 211 211 - ensure_dir cache_dir; 212 212 - ensure_dir state_dir; 213 213 - Option.iter (ensure_runtime_dir fs) runtime_dir; 214 214 - { 215 215 - app_name; 216 216 - config_dir; 217 217 - config_dir_source; 218 218 - data_dir; 219 219 - data_dir_source; 220 220 - cache_dir; 221 221 - cache_dir_source; 222 222 - state_dir; 223 223 - state_dir_source; 224 224 - runtime_dir; 225 225 - runtime_dir_source; 226 226 - config_dirs; 227 227 - data_dirs; 228 228 - } 229 229 - 230 230 - let app_name t = t.app_name 231 231 - let config_dir t = t.config_dir 232 232 - let data_dir t = t.data_dir 233 233 - let cache_dir t = t.cache_dir 234 234 - let state_dir t = t.state_dir 235 235 - let runtime_dir t = t.runtime_dir 236 236 - let config_dirs t = t.config_dirs 237 237 - let data_dirs t = t.data_dirs 238 238 - 239 239 - (* Check if an Eio exception indicates a missing file/directory *) 240 240 - let is_not_found_error = function 241 241 - | Eio.Io (Eio.Fs.E (Eio.Fs.Not_found _), _) -> true 242 242 - | Eio.Io (Eio.Fs.E (Eio.Fs.Permission_denied _), _) -> true 243 243 - | _ -> false 244 244 - 245 245 - (* File search following XDG specification *) 246 246 - let find_file_in_dirs dirs filename = 247 247 - let rec search_dirs = function 248 248 - | [] -> None 249 249 - | dir :: remaining_dirs -> ( 250 250 - let file_path = Eio.Path.(dir / filename) in 251 251 - try 252 252 - (* Try to check if file exists and is readable *) 253 253 - let _ = Eio.Path.stat ~follow:true file_path in 254 254 - Some file_path 255 255 - with exn when is_not_found_error exn -> 256 256 - (* File is inaccessible (non-existent, permissions, etc.) 257 257 - Skip and continue with next directory per XDG spec *) 258 258 - search_dirs remaining_dirs) 259 259 - in 260 260 - search_dirs dirs 261 261 - 262 262 - let find_config_file t filename = 263 263 - (* Search user config dir first, then system config dirs *) 264 264 - find_file_in_dirs (t.config_dir :: t.config_dirs) filename 265 265 - 266 266 - let find_data_file t filename = 267 267 - (* Search user data dir first, then system data dirs *) 268 268 - find_file_in_dirs (t.data_dir :: t.data_dirs) filename 269 269 - 270 270 - let pp ?(brief = false) ?(sources = false) ppf t = 271 271 - let pp_source ppf = function 272 272 - | Default -> Fmt.(styled `Faint string) ppf "default" 273 273 - | Env var -> Fmt.pf ppf "%a" Fmt.(styled `Yellow string) ("env(" ^ var ^ ")") 274 274 - | Cmdline -> Fmt.(styled `Blue string) ppf "cmdline" 275 275 - in 276 276 - let pp_path_with_source ppf path source = 277 277 - if sources then 278 278 - Fmt.pf ppf "%a %a" 279 279 - Fmt.(styled `Green Eio.Path.pp) 280 280 - path 281 281 - Fmt.(styled `Faint (brackets pp_source)) 282 282 - source 283 283 - else Fmt.(styled `Green Eio.Path.pp) ppf path 284 284 - in 285 285 - let pp_path_opt_with_source ppf path_opt source = 286 286 - match path_opt with 287 287 - | None -> 288 288 - if sources then 289 289 - Fmt.pf ppf "%a %a" 290 290 - Fmt.(styled `Red string) 291 291 - "<none>" 292 292 - Fmt.(styled `Faint (brackets pp_source)) 293 293 - source 294 294 - else Fmt.(styled `Red string) ppf "<none>" 295 295 - | Some path -> pp_path_with_source ppf path source 296 296 - in 297 297 - let pp_paths ppf paths = 298 298 - Fmt.(list ~sep:(any ";@ ") (styled `Green Eio.Path.pp)) ppf paths 299 299 - in 300 300 - if brief then 301 301 - Fmt.pf ppf "%a config=%a data=%a>" 302 302 - Fmt.(styled `Cyan string) 303 303 - ("<xdg:" ^ t.app_name) 304 304 - (fun ppf (path, source) -> pp_path_with_source ppf path source) 305 305 - (t.config_dir, t.config_dir_source) 306 306 - (fun ppf (path, source) -> pp_path_with_source ppf path source) 307 307 - (t.data_dir, t.data_dir_source) 308 308 - else ( 309 309 - Fmt.pf ppf "@[<v>%a@," 310 310 - Fmt.(styled `Bold string) 311 311 - ("XDG directories for '" ^ t.app_name ^ "':"); 312 312 - Fmt.pf ppf "@[<v 2>%a@," Fmt.(styled `Bold string) "User directories:"; 313 313 - Fmt.pf ppf "%a %a@," 314 314 - Fmt.(styled `Cyan string) 315 315 - "config:" 316 316 - (fun ppf (path, source) -> pp_path_with_source ppf path source) 317 317 - (t.config_dir, t.config_dir_source); 318 318 - Fmt.pf ppf "%a %a@," 319 319 - Fmt.(styled `Cyan string) 320 320 - "data:" 321 321 - (fun ppf (path, source) -> pp_path_with_source ppf path source) 322 322 - (t.data_dir, t.data_dir_source); 323 323 - Fmt.pf ppf "%a %a@," 324 324 - Fmt.(styled `Cyan string) 325 325 - "cache:" 326 326 - (fun ppf (path, source) -> pp_path_with_source ppf path source) 327 327 - (t.cache_dir, t.cache_dir_source); 328 328 - Fmt.pf ppf "%a %a@," 329 329 - Fmt.(styled `Cyan string) 330 330 - "state:" 331 331 - (fun ppf (path, source) -> pp_path_with_source ppf path source) 332 332 - (t.state_dir, t.state_dir_source); 333 333 - Fmt.pf ppf "%a %a@]@," 334 334 - Fmt.(styled `Cyan string) 335 335 - "runtime:" 336 336 - (fun ppf (path_opt, source) -> 337 337 - pp_path_opt_with_source ppf path_opt source) 338 338 - (t.runtime_dir, t.runtime_dir_source); 339 339 - Fmt.pf ppf "@[<v 2>%a@," Fmt.(styled `Bold string) "System directories:"; 340 340 - Fmt.pf ppf "%a [@[<hov>%a@]]@," 341 341 - Fmt.(styled `Cyan string) 342 342 - "config_dirs:" pp_paths t.config_dirs; 343 343 - Fmt.pf ppf "%a [@[<hov>%a@]]@]@]" 344 344 - Fmt.(styled `Cyan string) 345 345 - "data_dirs:" pp_paths t.data_dirs) 346 346 - 347 347 - module Cmd = struct 348 348 - type xdg_t = t 349 349 - type 'a with_source = { value : 'a option; source : source } 350 350 - 351 351 - type t = { 352 352 - config_dir : string with_source; 353 353 - data_dir : string with_source; 354 354 - cache_dir : string with_source; 355 355 - state_dir : string with_source; 356 356 - runtime_dir : string with_source; 357 357 - } 358 358 - 359 359 - type dir = [ `Config | `Cache | `Data | `State | `Runtime ] 360 360 - 361 361 - let term app_name fs ?(dirs = [ `Config; `Data; `Cache; `State; `Runtime ]) () 362 362 - = 363 363 - let open Cmdliner in 364 364 - let app_upper = String.uppercase_ascii app_name in 365 365 - let show_paths = 366 366 - let doc = "Show only the resolved directory paths without formatting" in 367 367 - Arg.(value & flag & info [ "show-paths" ] ~doc) 368 368 - in 369 369 - let has_dir d = List.mem d dirs in 370 370 - let make_dir_arg ~enabled name env_suffix xdg_var default_path = 371 371 - if not enabled then 372 372 - (* Return a term that always gives the environment-only result *) 373 373 - Term.( 374 374 - const (fun () -> 375 375 - let app_env = app_upper ^ "_" ^ env_suffix in 376 376 - match Sys.getenv_opt app_env with 377 377 - | Some v when v <> "" -> { value = Some v; source = Env app_env } 378 378 - | Some _ | None -> ( 379 379 - match Sys.getenv_opt xdg_var with 380 380 - | Some v -> { value = Some v; source = Env xdg_var } 381 381 - | None -> { value = None; source = Default })) 382 382 - $ const ()) 383 383 - else 384 384 - let app_env = app_upper ^ "_" ^ env_suffix in 385 385 - let doc = 386 386 - match default_path with 387 387 - | Some path -> 388 388 - Printf.sprintf 389 389 - "Override %s directory. Can also be set with %s or %s. \ 390 390 - Default: %s" 391 391 - name app_env xdg_var path 392 392 - | None -> 393 393 - Printf.sprintf 394 394 - "Override %s directory. Can also be set with %s or %s. No \ 395 395 - default value." 396 396 - name app_env xdg_var 397 397 - in 398 398 - let arg = 399 399 - Arg.( 400 400 - value 401 401 - & opt (some string) None 402 402 - & info [ name ^ "-dir" ] ~docv:"DIR" ~doc) 403 403 - in 404 404 - Term.( 405 405 - const (fun cmdline_val -> 406 406 - match cmdline_val with 407 407 - | Some v -> { value = Some v; source = Cmdline } 408 408 - | None -> ( 409 409 - match Sys.getenv_opt app_env with 410 410 - | Some v when v <> "" -> 411 411 - { value = Some v; source = Env app_env } 412 412 - | Some _ | None -> ( 413 413 - match Sys.getenv_opt xdg_var with 414 414 - | Some v -> { value = Some v; source = Env xdg_var } 415 415 - | None -> { value = None; source = Default }))) 416 416 - $ arg) 417 417 - in 418 418 - let home_prefix = "\\$HOME" in 419 419 - let config_dir = 420 420 - make_dir_arg ~enabled:(has_dir `Config) "config" "CONFIG_DIR" 421 421 - "XDG_CONFIG_HOME" 422 422 - (Some (home_prefix ^ "/.config/" ^ app_name)) 423 423 - in 424 424 - let data_dir = 425 425 - make_dir_arg ~enabled:(has_dir `Data) "data" "DATA_DIR" "XDG_DATA_HOME" 426 426 - (Some (home_prefix ^ "/.local/share/" ^ app_name)) 427 427 - in 428 428 - let cache_dir = 429 429 - make_dir_arg ~enabled:(has_dir `Cache) "cache" "CACHE_DIR" 430 430 - "XDG_CACHE_HOME" 431 431 - (Some (home_prefix ^ "/.cache/" ^ app_name)) 432 432 - in 433 433 - let state_dir = 434 434 - make_dir_arg ~enabled:(has_dir `State) "state" "STATE_DIR" 435 435 - "XDG_STATE_HOME" 436 436 - (Some (home_prefix ^ "/.local/state/" ^ app_name)) 437 437 - in 438 438 - let runtime_dir = 439 439 - make_dir_arg ~enabled:(has_dir `Runtime) "runtime" "RUNTIME_DIR" 440 440 - "XDG_RUNTIME_DIR" None 441 441 - in 442 442 - Term.( 443 443 - const 444 444 - (fun 445 445 - show_paths_flag 446 446 - config_dir_ws 447 447 - data_dir_ws 448 448 - cache_dir_ws 449 449 - state_dir_ws 450 450 - runtime_dir_ws 451 451 - -> 452 452 - let config = 453 453 - { 454 454 - config_dir = config_dir_ws; 455 455 - data_dir = data_dir_ws; 456 456 - cache_dir = cache_dir_ws; 457 457 - state_dir = state_dir_ws; 458 458 - runtime_dir = runtime_dir_ws; 459 459 - } 460 460 - in 461 461 - let home_path = get_home_dir fs in 462 462 - (* First validate all standard XDG environment variables *) 463 463 - validate_standard_xdg_vars (); 464 464 - let xdg_ctx = Xdg.create ~env:Sys.getenv_opt () in 465 465 - (* Helper to resolve directory from config with source tracking *) 466 466 - let resolve_from_config config_ws xdg_getter = 467 467 - match config_ws.value with 468 468 - | Some dir -> (resolve_path fs home_path dir, config_ws.source) 469 469 - | None -> 470 470 - let xdg_base = xdg_getter xdg_ctx in 471 471 - let base_path = resolve_path fs home_path xdg_base in 472 472 - (Eio.Path.(base_path / app_name), config_ws.source) 473 473 - in 474 474 - (* User directories *) 475 475 - let config_dir, config_dir_source = 476 476 - resolve_from_config config.config_dir Xdg.config_dir 477 477 - in 478 478 - let data_dir, data_dir_source = 479 479 - resolve_from_config config.data_dir Xdg.data_dir 480 480 - in 481 481 - let cache_dir, cache_dir_source = 482 482 - resolve_from_config config.cache_dir Xdg.cache_dir 483 483 - in 484 484 - let state_dir, state_dir_source = 485 485 - resolve_from_config config.state_dir Xdg.state_dir 486 486 - in 487 487 - (* Runtime directory *) 488 488 - let runtime_dir, runtime_dir_source = 489 489 - match config.runtime_dir.value with 490 490 - | Some dir -> 491 491 - (Some (resolve_path fs home_path dir), config.runtime_dir.source) 492 492 - | None -> 493 493 - ( Option.map 494 494 - (fun base -> 495 495 - let base_path = resolve_path fs home_path base in 496 496 - Eio.Path.(base_path / app_name)) 497 497 - (Xdg.runtime_dir xdg_ctx), 498 498 - config.runtime_dir.source ) 499 499 - in 500 500 - (* System directories - reuse shared helper *) 501 501 - let config_dirs = 502 502 - resolve_system_dirs fs home_path app_name "CONFIG_DIRS" 503 503 - "XDG_CONFIG_DIRS" [ "/etc/xdg" ] 504 504 - in 505 505 - let data_dirs = 506 506 - resolve_system_dirs fs home_path app_name "DATA_DIRS" 507 507 - "XDG_DATA_DIRS" 508 508 - [ "/usr/local/share"; "/usr/share" ] 509 509 - in 510 510 - ensure_dir config_dir; 511 511 - ensure_dir data_dir; 512 512 - ensure_dir cache_dir; 513 513 - ensure_dir state_dir; 514 514 - Option.iter (ensure_runtime_dir fs) runtime_dir; 515 515 - let xdg = 516 516 - { 517 517 - app_name; 518 518 - config_dir; 519 519 - config_dir_source; 520 520 - data_dir; 521 521 - data_dir_source; 522 522 - cache_dir; 523 523 - cache_dir_source; 524 524 - state_dir; 525 525 - state_dir_source; 526 526 - runtime_dir; 527 527 - runtime_dir_source; 528 528 - config_dirs; 529 529 - data_dirs; 530 530 - } 531 531 - in 532 532 - (* Handle --show-paths option *) 533 533 - if show_paths_flag then ( 534 534 - let print_path name path = 535 535 - match path with 536 536 - | None -> Printf.printf "%s: <none>\n" name 537 537 - | Some p -> Printf.printf "%s: %s\n" name (Eio.Path.native_exn p) 538 538 - in 539 539 - let print_paths name paths = 540 540 - match paths with 541 541 - | [] -> Printf.printf "%s: []\n" name 542 542 - | paths -> 543 543 - let paths_str = 544 544 - String.concat ":" (List.map Eio.Path.native_exn paths) 545 545 - in 546 546 - Printf.printf "%s: %s\n" name paths_str 547 547 - in 548 548 - print_path "config_dir" (Some config_dir); 549 549 - print_path "data_dir" (Some data_dir); 550 550 - print_path "cache_dir" (Some cache_dir); 551 551 - print_path "state_dir" (Some state_dir); 552 552 - print_path "runtime_dir" runtime_dir; 553 553 - print_paths "config_dirs" config_dirs; 554 554 - print_paths "data_dirs" data_dirs; 555 555 - Stdlib.exit 0); 556 556 - (xdg, config)) 557 557 - $ show_paths $ config_dir $ data_dir $ cache_dir $ state_dir $ runtime_dir) 558 558 - 559 559 - let cache_term app_name = 560 560 - let open Cmdliner in 561 561 - let app_upper = String.uppercase_ascii app_name in 562 562 - let app_env = app_upper ^ "_CACHE_DIR" in 563 563 - let xdg_var = "XDG_CACHE_HOME" in 564 564 - let home = Sys.getenv "HOME" in 565 565 - let default_path = home ^ "/.cache/" ^ app_name in 566 566 - 567 567 - let doc = 568 568 - Printf.sprintf 569 569 - "Override cache directory. Can also be set with %s or %s. Default: %s" 570 570 - app_env xdg_var default_path 571 571 - in 572 572 - 573 573 - let arg = 574 574 - Arg.( 575 575 - value & opt string default_path 576 576 - & info [ "cache-dir"; "c" ] ~docv:"DIR" ~doc) 577 577 - in 578 578 - 579 579 - Term.( 580 580 - const (fun cmdline_val -> 581 581 - (* Check command line first *) 582 582 - if cmdline_val <> default_path then cmdline_val 583 583 - else 584 584 - (* Then check app-specific env var *) 585 585 - match Sys.getenv_opt app_env with 586 586 - | Some v when v <> "" -> v 587 587 - | _ -> ( 588 588 - (* Then check XDG env var *) 589 589 - match Sys.getenv_opt xdg_var with 590 590 - | Some v when v <> "" -> v ^ "/" ^ app_name 591 591 - | _ -> default_path)) 592 592 - $ arg) 593 593 - 594 594 - let env_docs app_name = 595 595 - let app_upper = String.uppercase_ascii app_name in 596 596 - Printf.sprintf 597 597 - {| 598 598 - Configuration Precedence (follows standard Unix conventions): 599 599 - 1. Command-line flags (e.g., --config-dir) - highest priority 600 600 - 2. Application-specific environment variable (e.g., %s_CONFIG_DIR) 601 601 - 3. XDG standard environment variable (e.g., XDG_CONFIG_HOME) 602 602 - 4. Default path (e.g., ~/.config/%s) - lowest priority 603 603 - 604 604 - This allows per-application overrides without affecting other XDG-compliant programs. 605 605 - For example, setting %s_CONFIG_DIR only changes the config directory for %s, 606 606 - while XDG_CONFIG_HOME affects all XDG-compliant applications. 607 607 - 608 608 - Application-specific variables: 609 609 - %s_CONFIG_DIR Override config directory for %s only 610 610 - %s_DATA_DIR Override data directory for %s only 611 611 - %s_CACHE_DIR Override cache directory for %s only 612 612 - %s_STATE_DIR Override state directory for %s only 613 613 - %s_RUNTIME_DIR Override runtime directory for %s only 614 614 - 615 615 - XDG standard variables (shared by all XDG applications): 616 616 - XDG_CONFIG_HOME User configuration directory (default: ~/.config/%s) 617 617 - XDG_DATA_HOME User data directory (default: ~/.local/share/%s) 618 618 - XDG_CACHE_HOME User cache directory (default: ~/.cache/%s) 619 619 - XDG_STATE_HOME User state directory (default: ~/.local/state/%s) 620 620 - XDG_RUNTIME_DIR User runtime directory (no default) 621 621 - XDG_CONFIG_DIRS System configuration directories (default: /etc/xdg/%s) 622 622 - XDG_DATA_DIRS System data directories (default: /usr/local/share/%s:/usr/share/%s) 623 623 - |} 624 624 - app_upper app_name app_upper app_name app_upper app_name app_upper 625 625 - app_name app_upper app_name app_upper app_name app_upper app_name app_name 626 626 - app_name app_name app_name app_name app_name app_name 627 627 - 628 628 - let pp ppf config = 629 629 - let pp_source ppf = function 630 630 - | Default -> Fmt.(styled `Faint string) ppf "default" 631 631 - | Env var -> 632 632 - Fmt.pf ppf "%a" Fmt.(styled `Yellow string) ("env(" ^ var ^ ")") 633 633 - | Cmdline -> Fmt.(styled `Blue string) ppf "cmdline" 634 634 - in 635 635 - let pp_with_source name ppf ws = 636 636 - match ws.value with 637 637 - | None when ws.source = Default -> () 638 638 - | None -> 639 639 - Fmt.pf ppf "@,%a %a %a" 640 640 - Fmt.(styled `Cyan string) 641 641 - (name ^ ":") 642 642 - Fmt.(styled `Red string) 643 643 - "<unset>" 644 644 - Fmt.(styled `Faint (brackets pp_source)) 645 645 - ws.source 646 646 - | Some value -> 647 647 - Fmt.pf ppf "@,%a %a %a" 648 648 - Fmt.(styled `Cyan string) 649 649 - (name ^ ":") 650 650 - Fmt.(styled `Green string) 651 651 - value 652 652 - Fmt.(styled `Faint (brackets pp_source)) 653 653 - ws.source 654 654 - in 655 655 - Fmt.pf ppf "@[<v>%a%a%a%a%a%a@]" 656 656 - Fmt.(styled `Bold string) 657 657 - "XDG config:" 658 658 - (pp_with_source "config_dir") 659 659 - config.config_dir 660 660 - (pp_with_source "data_dir") 661 661 - config.data_dir 662 662 - (pp_with_source "cache_dir") 663 663 - config.cache_dir 664 664 - (pp_with_source "state_dir") 665 665 - config.state_dir 666 666 - (pp_with_source "runtime_dir") 667 667 - config.runtime_dir 668 668 - end

-441

xdge/lib/xdge.mli

reviewed

··· 1 1 - (*--------------------------------------------------------------------------- 2 2 - Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved. 3 3 - SPDX-License-Identifier: ISC 4 4 - ---------------------------------------------------------------------------*) 5 5 - 6 6 - (** XDG Base Directory Specification support with Eio capabilities 7 7 - 8 8 - This library provides an OCaml implementation of the XDG Base Directory 9 9 - Specification with Eio filesystem integration. The XDG specification defines 10 10 - standard locations for user-specific and system-wide application files, 11 11 - helping to keep user home directories clean and organized. 12 12 - 13 13 - The specification is available at: 14 14 - {{:https://specifications.freedesktop.org/basedir-spec/latest/} XDG Base 15 15 - Directory Specification} 16 16 - 17 17 - {b Key Concepts:} 18 18 - 19 19 - The XDG specification defines several types of directories: 20 20 - - {b User directories}: Store user-specific files (config, data, cache, 21 21 - state, runtime) 22 22 - - {b System directories}: Store system-wide files shared across users 23 23 - - {b Precedence}: User directories take precedence over system directories 24 24 - - {b Application isolation}: Each application gets its own subdirectory 25 25 - 26 26 - {b Environment Variable Precedence:} 27 27 - 28 28 - This library follows a three-level precedence system: 29 29 - + Application-specific variables (e.g., [MYAPP_CONFIG_DIR]) - highest 30 30 - priority 31 31 - + XDG standard variables (e.g., [XDG_CONFIG_HOME]) 32 32 - + Default paths (e.g., [$HOME/.config]) - lowest priority 33 33 - 34 34 - This allows fine-grained control over directory locations without affecting 35 35 - other XDG-compliant applications. 36 36 - 37 37 - {b Directory Creation:} 38 38 - 39 39 - All directories are automatically created with appropriate permissions 40 40 - (0o755) when accessed, except for runtime directories which require stricter 41 41 - permissions as per the specification. 42 42 - 43 43 - @see <https://specifications.freedesktop.org/basedir-spec/latest/> 44 44 - XDG Base Directory Specification 45 45 - 46 46 - {2 Related Libraries} 47 47 - 48 48 - This library is used by: 49 49 - 50 50 - {ul 51 51 - {- [Requests] - HTTP client that uses Xdge for cookie persistence paths} 52 52 - {- [Cookeio_jar] - Cookie jar with XDG-compliant storage}} *) 53 53 - 54 54 - type t 55 55 - (** The main XDG context type containing all directory paths for an application. 56 56 - 57 57 - A value of type [t] represents the complete XDG directory structure for a 58 58 - specific application, including both user-specific and system-wide 59 59 - directories. All paths are resolved at creation time and are absolute paths 60 60 - within the Eio filesystem. *) 61 61 - 62 62 - (** {1 Exceptions} *) 63 63 - 64 64 - exception Invalid_xdg_path of string 65 65 - (** Exception raised when XDG environment variables contain invalid paths. 66 66 - 67 67 - The XDG specification requires all paths in environment variables to be 68 68 - absolute. This exception is raised when a relative path is found. *) 69 69 - 70 70 - (** {1 Construction} *) 71 71 - 72 72 - val create : Eio.Fs.dir_ty Eio.Path.t -> string -> t 73 73 - (** [create fs app_name] creates an XDG context for the given application. 74 74 - 75 75 - This function initializes the complete XDG directory structure for your 76 76 - application, resolving all paths according to the environment variables and 77 77 - creating directories as needed. 78 78 - 79 79 - @param fs The Eio filesystem providing filesystem access 80 80 - @param app_name The name of your application (used as subdirectory name) 81 81 - 82 82 - {b Path Resolution:} 83 83 - 84 84 - For each directory type, the following precedence is used: 85 85 - + Application-specific environment variable (e.g., [MYAPP_CONFIG_DIR]) 86 86 - + XDG standard environment variable (e.g., [XDG_CONFIG_HOME]) 87 87 - + Default path as specified in the XDG specification 88 88 - 89 89 - {b Example:} 90 90 - {[ 91 91 - let xdg = Xdge.create env#fs "myapp" in 92 92 - let config = Xdge.config_dir xdg in 93 93 - (* config is now <fs:$HOME/.config/myapp> or the overridden path *) 94 94 - ]} 95 95 - 96 96 - All directories are created with permissions 0o755 if they don't exist, 97 97 - except for runtime directories which are created with 0o700 permissions and 98 98 - validated according to the XDG specification. 99 99 - 100 100 - @raise Invalid_xdg_path if any environment variable contains a relative path 101 101 - *) 102 102 - 103 103 - (** {1 Accessors} *) 104 104 - 105 105 - val app_name : t -> string 106 106 - (** [app_name t] returns the application name used when creating this XDG 107 107 - context. 108 108 - 109 109 - This is the name that was passed to {!create} and is used as the 110 110 - subdirectory name within each XDG base directory. *) 111 111 - 112 112 - (** {1 Base Directories} *) 113 113 - 114 114 - val config_dir : t -> Eio.Fs.dir_ty Eio.Path.t 115 115 - (** [config_dir t] returns the path to user-specific configuration files. 116 116 - 117 117 - {b Purpose:} Store user preferences, settings, and configuration files. 118 118 - Configuration files should be human-readable when possible. 119 119 - 120 120 - {b Environment Variables:} 121 121 - - [${APP_NAME}_CONFIG_DIR]: Application-specific override (highest priority) 122 122 - - [XDG_CONFIG_HOME]: XDG standard variable 123 123 - - Default: [$HOME/.config/{app_name}] 124 124 - 125 125 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 126 126 - XDG_CONFIG_HOME specification *) 127 127 - 128 128 - val data_dir : t -> Eio.Fs.dir_ty Eio.Path.t 129 129 - (** [data_dir t] returns the path to user-specific data files. 130 130 - 131 131 - {b Purpose:} Store persistent application data that should be preserved 132 132 - across application restarts and system reboots. This data is typically not 133 133 - modified by users directly. 134 134 - 135 135 - {b Environment Variables:} 136 136 - - [${APP_NAME}_DATA_DIR]: Application-specific override (highest priority) 137 137 - - [XDG_DATA_HOME]: XDG standard variable 138 138 - - Default: [$HOME/.local/share/{app_name}] 139 139 - 140 140 - {b Example Files:} 141 141 - - Application databases 142 142 - - User-generated content (documents, projects) 143 143 - - Downloaded resources 144 144 - - Application plugins or extensions 145 145 - 146 146 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 147 147 - XDG_DATA_HOME specification *) 148 148 - 149 149 - val cache_dir : t -> Eio.Fs.dir_ty Eio.Path.t 150 150 - (** [cache_dir t] returns the path to user-specific cache files. 151 151 - 152 152 - {b Purpose:} Store non-essential cached data that can be regenerated if 153 153 - deleted. The application should remain functional if this directory is 154 154 - cleared, though performance may be temporarily impacted. 155 155 - 156 156 - {b Environment Variables:} 157 157 - - [${APP_NAME}_CACHE_DIR]: Application-specific override (highest priority) 158 158 - - [XDG_CACHE_HOME]: XDG standard variable 159 159 - - Default: [$HOME/.cache/{app_name}] 160 160 - 161 161 - {b Example Files:} 162 162 - - Downloaded thumbnails and previews 163 163 - - Compiled bytecode or object files 164 164 - - Network response caches 165 165 - - Temporary computation results 166 166 - 167 167 - Users may clear cache directories to free disk space, so always check for 168 168 - cache validity and be prepared to regenerate data. 169 169 - 170 170 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 171 171 - XDG_CACHE_HOME specification *) 172 172 - 173 173 - val state_dir : t -> Eio.Fs.dir_ty Eio.Path.t 174 174 - (** [state_dir t] returns the path to user-specific state files. 175 175 - 176 176 - {b Purpose:} Store persistent state data that should be preserved between 177 177 - application restarts but is not important enough to be user data. This 178 178 - includes application state that can be regenerated but would impact the user 179 179 - experience if lost. 180 180 - 181 181 - {b Environment Variables:} 182 182 - - [${APP_NAME}_STATE_DIR]: Application-specific override (highest priority) 183 183 - - [XDG_STATE_HOME]: XDG standard variable 184 184 - - Default: [$HOME/.local/state/{app_name}] 185 185 - 186 186 - {b Example Files:} 187 187 - - Application history (recently used files, command history) 188 188 - - Current application state (window positions, open tabs) 189 189 - - Logs and journal files 190 190 - - Undo/redo history 191 191 - 192 192 - {b Comparison with other directories:} 193 193 - - Unlike cache: State should persist between reboots 194 194 - - Unlike data: State can be regenerated (though inconvenient) 195 195 - - Unlike config: State changes frequently during normal use 196 196 - 197 197 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 198 198 - XDG_STATE_HOME specification *) 199 199 - 200 200 - val runtime_dir : t -> Eio.Fs.dir_ty Eio.Path.t option 201 201 - (** [runtime_dir t] returns the path to user-specific runtime files. 202 202 - 203 203 - {b Purpose:} Store runtime files such as sockets, named pipes, and process 204 204 - IDs. These files are only valid for the duration of the user's login 205 205 - session. 206 206 - 207 207 - {b Environment Variables:} 208 208 - - [${APP_NAME}_RUNTIME_DIR]: Application-specific override (highest 209 209 - priority) 210 210 - - [XDG_RUNTIME_DIR]: XDG standard variable 211 211 - - Default: None (returns [None] if not set) 212 212 - 213 213 - {b Required Properties (per specification):} 214 214 - - Owned by the user with access mode 0700 215 215 - - Bound to the user login session lifetime 216 216 - - Located on a local filesystem (not networked) 217 217 - - Fully-featured by the OS (supporting proper locking, etc.) 218 218 - 219 219 - {b Example Files:} 220 220 - - Unix domain sockets 221 221 - - Named pipes (FIFOs) 222 222 - - Lock files 223 223 - - Small process communication files 224 224 - 225 225 - This may return [None] if no suitable runtime directory is available. 226 226 - Applications should handle this gracefully, perhaps by falling back to 227 227 - [/tmp] with appropriate security measures. 228 228 - 229 229 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 230 230 - XDG_RUNTIME_DIR specification *) 231 231 - 232 232 - (** {1 System Directories} *) 233 233 - 234 234 - val config_dirs : t -> Eio.Fs.dir_ty Eio.Path.t list 235 235 - (** [config_dirs t] returns search paths for system-wide configuration files. 236 236 - 237 237 - {b Purpose:} Provide a search path for configuration files that are shared 238 238 - between multiple users. Files in user-specific {!config_dir} take precedence 239 239 - over these system directories. 240 240 - 241 241 - {b Environment Variables:} 242 242 - - [${APP_NAME}_CONFIG_DIRS]: Application-specific override (highest 243 243 - priority) 244 244 - - [XDG_CONFIG_DIRS]: XDG standard variable (colon-separated list) 245 245 - - Default: [[/etc/xdg/{app_name}]] 246 246 - 247 247 - {b Search Order:} Directories are ordered by preference, with earlier 248 248 - entries taking precedence over later ones. When looking for a configuration 249 249 - file, search {!config_dir} first, then each directory in this list. 250 250 - 251 251 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 252 252 - XDG_CONFIG_DIRS specification *) 253 253 - 254 254 - val data_dirs : t -> Eio.Fs.dir_ty Eio.Path.t list 255 255 - (** [data_dirs t] returns search paths for system-wide data files. 256 256 - 257 257 - {b Purpose:} Provide a search path for data files that are shared between 258 258 - multiple users. Files in user-specific {!data_dir} take precedence over 259 259 - these system directories. 260 260 - 261 261 - {b Environment Variables:} 262 262 - - [${APP_NAME}_DATA_DIRS]: Application-specific override (highest priority) 263 263 - - [XDG_DATA_DIRS]: XDG standard variable (colon-separated list) 264 264 - - Default: [[/usr/local/share/{app_name}; /usr/share/{app_name}]] 265 265 - 266 266 - {b Search Order:} Directories are ordered by preference, with earlier 267 267 - entries taking precedence over later ones. When looking for a data file, 268 268 - search {!data_dir} first, then each directory in this list. 269 269 - 270 270 - {b Example Files:} 271 271 - - Application icons and themes 272 272 - - Desktop files 273 273 - - Shared application resources 274 274 - - Documentation files 275 275 - - Default templates 276 276 - 277 277 - @see <https://specifications.freedesktop.org/basedir-spec/latest/#variables> 278 278 - XDG_DATA_DIRS specification *) 279 279 - 280 280 - (** {1 File Search} *) 281 281 - 282 282 - val find_config_file : t -> string -> Eio.Fs.dir_ty Eio.Path.t option 283 283 - (** [find_config_file t filename] searches for a configuration file following 284 284 - XDG precedence. 285 285 - 286 286 - This function searches for the given filename in the user configuration 287 287 - directory first, then in system configuration directories in order of 288 288 - preference. Files that are inaccessible (due to permissions, non-existence, 289 289 - etc.) are silently skipped as per the XDG specification. 290 290 - 291 291 - @param t The XDG context 292 292 - @param filename The name of the file to search for 293 293 - @return [Some path] if found, [None] if not found in any directory 294 294 - 295 295 - {b Search Order:} 1. User config directory ({!config_dir}) 2. System config 296 296 - directories ({!config_dirs}) in preference order *) 297 297 - 298 298 - val find_data_file : t -> string -> Eio.Fs.dir_ty Eio.Path.t option 299 299 - (** [find_data_file t filename] searches for a data file following XDG 300 300 - precedence. 301 301 - 302 302 - This function searches for the given filename in the user data directory 303 303 - first, then in system data directories in order of preference. Files that 304 304 - are inaccessible (due to permissions, non-existence, etc.) are silently 305 305 - skipped as per the XDG specification. 306 306 - 307 307 - @param t The XDG context 308 308 - @param filename The name of the file to search for 309 309 - @return [Some path] if found, [None] if not found in any directory 310 310 - 311 311 - {b Search Order:} 1. User data directory ({!data_dir}) 2. System data 312 312 - directories ({!data_dirs}) in preference order *) 313 313 - 314 314 - (** {1 Pretty Printing} *) 315 315 - 316 316 - val pp : ?brief:bool -> ?sources:bool -> Format.formatter -> t -> unit 317 317 - (** [pp ?brief ?sources ppf t] pretty prints the XDG directory configuration. 318 318 - 319 319 - @param brief If [true], prints a compact one-line summary (default: [false]) 320 320 - @param sources 321 321 - If [true], shows the source of each directory value, indicating whether it 322 322 - came from defaults, environment variables, or command line (default: 323 323 - [false]) 324 324 - @param ppf The formatter to print to 325 325 - @param t The XDG context to print 326 326 - 327 327 - {b Output formats:} 328 328 - - Normal: Multi-line detailed view of all directories 329 329 - - Brief: Single line showing app name and key directories 330 330 - - With sources: Adds annotations showing where each path came from *) 331 331 - 332 332 - (** {1 Cmdliner Integration} *) 333 333 - 334 334 - module Cmd : sig 335 335 - (** The type of the outer XDG context *) 336 336 - type xdg_t = t 337 337 - (** Cmdliner integration for XDG directory configuration. 338 338 - 339 339 - This module provides integration with the Cmdliner library, allowing XDG 340 340 - directories to be configured via command-line arguments while respecting 341 341 - the precedence of environment variables. *) 342 342 - 343 343 - type t 344 344 - (** Type of XDG configuration gathered from command-line and environment. 345 345 - 346 346 - This contains all XDG directory paths along with their sources, as 347 347 - determined by command-line arguments and environment variables. *) 348 348 - 349 349 - type dir = 350 350 - [ `Config (** User configuration files *) 351 351 - | `Cache (** User-specific cached data *) 352 352 - | `Data (** User-specific application data *) 353 353 - | `State (** User-specific state data (logs, history, etc.) *) 354 354 - | `Runtime (** User-specific runtime files (sockets, pipes, etc.) *) ] 355 355 - (** XDG directory types for specifying which directories an application needs. 356 356 - 357 357 - These allow applications to declare which XDG directories they use, 358 358 - enabling runtime systems to only provide the requested directories. *) 359 359 - 360 360 - val term : 361 361 - string -> 362 362 - Eio.Fs.dir_ty Eio.Path.t -> 363 363 - ?dirs:dir list -> 364 364 - unit -> 365 365 - (xdg_t * t) Cmdliner.Term.t 366 366 - (** [term app_name fs ?dirs ()] creates a Cmdliner term for XDG directory 367 367 - configuration. 368 368 - 369 369 - This function generates a Cmdliner term that handles XDG directory 370 370 - configuration through both command-line flags and environment variables, 371 371 - and directly returns the XDG context. Only command-line flags for the 372 372 - requested directories are generated. 373 373 - 374 374 - @param app_name 375 375 - The application name (used for environment variable prefixes) 376 376 - @param fs The Eio filesystem to use for path resolution 377 377 - @param dirs 378 378 - List of directories to include flags for (default: all directories) 379 379 - 380 380 - {b Generated Command-line Flags:} Only the flags for requested directories 381 381 - are generated: 382 382 - - [--config-dir DIR]: Override configuration directory (if [`Config] in 383 383 - dirs) 384 384 - - [--data-dir DIR]: Override data directory (if [`Data] in dirs) 385 385 - - [--cache-dir DIR]: Override cache directory (if [`Cache] in dirs) 386 386 - - [--state-dir DIR]: Override state directory (if [`State] in dirs) 387 387 - - [--runtime-dir DIR]: Override runtime directory (if [`Runtime] in dirs) 388 388 - 389 389 - {b Environment Variable Precedence:} For each directory type, the 390 390 - following precedence applies: 391 391 - + Command-line flag (e.g., [--config-dir]) - if enabled 392 392 - + Application-specific variable (e.g., [MYAPP_CONFIG_DIR]) 393 393 - + XDG standard variable (e.g., [XDG_CONFIG_HOME]) 394 394 - + Default value *) 395 395 - 396 396 - val cache_term : string -> string Cmdliner.Term.t 397 397 - (** [cache_term app_name] creates a Cmdliner term that provides just the cache 398 398 - directory path as a string, respecting XDG precedence. 399 399 - 400 400 - This is a convenience function for applications that only need cache 401 401 - directory configuration. It returns the resolved cache directory path 402 402 - directly as a string, suitable for use in other Cmdliner terms. 403 403 - 404 404 - @param app_name 405 405 - The application name (used for environment variable prefixes) 406 406 - 407 407 - {b Generated Command-line Flag:} 408 408 - - [--cache-dir DIR]: Override cache directory 409 409 - 410 410 - {b Environment Variable Precedence:} 411 411 - + Command-line flag ([--cache-dir]) 412 412 - + Application-specific variable (e.g., [MYAPP_CACHE_DIR]) 413 413 - + XDG standard variable ([XDG_CACHE_HOME]) 414 414 - + Default value ([$HOME/.cache/{app_name}]) *) 415 415 - 416 416 - val env_docs : string -> string 417 417 - (** [env_docs app_name] generates documentation for environment variables. 418 418 - 419 419 - Returns a formatted string documenting all environment variables that 420 420 - affect XDG directory configuration for the given application. This is 421 421 - useful for generating man pages or help text. 422 422 - 423 423 - @param app_name The application name 424 424 - @return A formatted documentation string 425 425 - 426 426 - {b Included Information:} 427 427 - - Configuration precedence rules 428 428 - - Application-specific environment variables 429 429 - - XDG standard environment variables 430 430 - - Default values for each directory type *) 431 431 - 432 432 - val pp : Format.formatter -> t -> unit 433 433 - (** [pp ppf config] pretty prints a Cmdliner configuration. 434 434 - 435 435 - This function formats the configuration showing each directory path along 436 436 - with its source, which is helpful for debugging configuration issues or 437 437 - displaying the current configuration to users. 438 438 - 439 439 - @param ppf The formatter to print to 440 440 - @param config The configuration to print *) 441 441 - end

-10

xdge/test/dune

reviewed

··· 1 1 - (executable 2 2 - (name xdg_example) 3 3 - (libraries xdge eio_main cmdliner fmt)) 4 4 - 5 5 - (executable 6 6 - (name test_paths) 7 7 - (libraries xdge eio eio_main)) 8 8 - 9 9 - (cram 10 10 - (deps xdg_example.exe test_paths.exe))

-110

xdge/test/test_paths.ml

reviewed

··· 1 1 - (*--------------------------------------------------------------------------- 2 2 - Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved. 3 3 - SPDX-License-Identifier: ISC 4 4 - ---------------------------------------------------------------------------*) 5 5 - 6 6 - let test_path_validation () = 7 7 - Printf.printf "Testing XDG path validation...\n"; 8 8 - (* Test absolute path validation for environment variables *) 9 9 - let test_relative_path_rejection env_var relative_path = 10 10 - Printf.printf "Testing rejection of relative path in %s...\n" env_var; 11 11 - Unix.putenv env_var relative_path; 12 12 - try 13 13 - Eio_main.run @@ fun env -> 14 14 - let _ = Xdge.create env#fs "test_validation" in 15 15 - Printf.printf "ERROR: Should have rejected relative path\n"; 16 16 - false 17 17 - with 18 18 - | Xdge.Invalid_xdg_path msg -> 19 19 - Printf.printf "SUCCESS: Correctly rejected relative path: %s\n" msg; 20 20 - true 21 21 - | exn -> 22 22 - Printf.printf "ERROR: Wrong exception: %s\n" (Printexc.to_string exn); 23 23 - false 24 24 - in 25 25 - let old_config_home = Sys.getenv_opt "XDG_CONFIG_HOME" in 26 26 - let old_data_dirs = Sys.getenv_opt "XDG_DATA_DIRS" in 27 27 - let success1 = 28 28 - test_relative_path_rejection "XDG_CONFIG_HOME" "relative/path" 29 29 - in 30 30 - let success2 = 31 31 - test_relative_path_rejection "XDG_DATA_DIRS" "rel1:rel2:/abs/path" 32 32 - in 33 33 - (* Restore original env vars *) 34 34 - (match old_config_home with 35 35 - | Some v -> Unix.putenv "XDG_CONFIG_HOME" v 36 36 - | None -> ( try Unix.putenv "XDG_CONFIG_HOME" "" with _ -> ())); 37 37 - (match old_data_dirs with 38 38 - | Some v -> Unix.putenv "XDG_DATA_DIRS" v 39 39 - | None -> ( try Unix.putenv "XDG_DATA_DIRS" "" with _ -> ())); 40 40 - success1 && success2 41 41 - 42 42 - let test_file_search () = 43 43 - Printf.printf "\nTesting XDG file search...\n"; 44 44 - Eio_main.run @@ fun env -> 45 45 - let xdg = Xdge.create env#fs "search_test" in 46 46 - (* Create test files *) 47 47 - let config_file = Eio.Path.(Xdge.config_dir xdg / "test.conf") in 48 48 - let data_file = Eio.Path.(Xdge.data_dir xdg / "test.dat") in 49 49 - Eio.Path.save ~create:(`Or_truncate 0o644) config_file "config content"; 50 50 - Eio.Path.save ~create:(`Or_truncate 0o644) data_file "data content"; 51 51 - (* Test finding existing files *) 52 52 - (match Xdge.find_config_file xdg "test.conf" with 53 53 - | Some path -> 54 54 - let content = Eio.Path.load path in 55 55 - Printf.printf "Found config file: %s\n" (String.trim content) 56 56 - | None -> Printf.printf "ERROR: Config file not found\n"); 57 57 - (match Xdge.find_data_file xdg "test.dat" with 58 58 - | Some path -> 59 59 - let content = Eio.Path.load path in 60 60 - Printf.printf "Found data file: %s\n" (String.trim content) 61 61 - | None -> Printf.printf "ERROR: Data file not found\n"); 62 62 - (* Test non-existent file *) 63 63 - match Xdge.find_config_file xdg "nonexistent.conf" with 64 64 - | Some _ -> Printf.printf "ERROR: Should not have found nonexistent file\n" 65 65 - | None -> Printf.printf "Correctly handled nonexistent file\n" 66 66 - 67 67 - let () = 68 68 - (* Check if we should run validation tests *) 69 69 - if Array.length Sys.argv > 1 && Sys.argv.(1) = "--validate" then ( 70 70 - let validation_success = test_path_validation () in 71 71 - test_file_search (); 72 72 - if validation_success then 73 73 - Printf.printf "\nAll path validation tests passed!\n" 74 74 - else Printf.printf "\nSome validation tests failed!\n") 75 75 - else 76 76 - (* Run original simple functionality test *) 77 77 - Eio_main.run @@ fun env -> 78 78 - let xdg = Xdge.create env#fs "path_test" in 79 79 - (* Test config subdirectory *) 80 80 - let profiles_path = Eio.Path.(Xdge.config_dir xdg / "profiles") in 81 81 - let profile_file = Eio.Path.(profiles_path / "default.json") in 82 82 - (try 83 83 - let content = Eio.Path.load profile_file in 84 84 - Printf.printf "config file content: %s" (String.trim content) 85 85 - with exn -> 86 86 - Printf.printf "config file error: %s" (Printexc.to_string exn)); 87 87 - (* Test data subdirectory *) 88 88 - let db_path = Eio.Path.(Xdge.data_dir xdg / "databases") in 89 89 - let db_file = Eio.Path.(db_path / "main.db") in 90 90 - (try 91 91 - let content = Eio.Path.load db_file in 92 92 - Printf.printf "\ndata file content: %s" (String.trim content) 93 93 - with exn -> 94 94 - Printf.printf "\ndata file error: %s" (Printexc.to_string exn)); 95 95 - (* Test cache subdirectory *) 96 96 - let cache_path = Eio.Path.(Xdge.cache_dir xdg / "thumbnails") in 97 97 - let cache_file = Eio.Path.(cache_path / "thumb1.png") in 98 98 - (try 99 99 - let content = Eio.Path.load cache_file in 100 100 - Printf.printf "\ncache file content: %s" (String.trim content) 101 101 - with exn -> 102 102 - Printf.printf "\ncache file error: %s" (Printexc.to_string exn)); 103 103 - (* Test state subdirectory *) 104 104 - let logs_path = Eio.Path.(Xdge.state_dir xdg / "logs") in 105 105 - let log_file = Eio.Path.(logs_path / "app.log") in 106 106 - try 107 107 - let content = Eio.Path.load log_file in 108 108 - Printf.printf "\nstate file content: %s\n" (String.trim content) 109 109 - with exn -> 110 110 - Printf.printf "\nstate file error: %s\n" (Printexc.to_string exn)

-4

xdge/test/test_paths.mli

reviewed

··· 1 1 - (*--------------------------------------------------------------------------- 2 2 - Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved. 3 3 - SPDX-License-Identifier: ISC 4 4 - ---------------------------------------------------------------------------*)

-379

xdge/test/xdg.t

reviewed

··· 1 1 - Test with default directories: 2 2 - 3 3 - $ export HOME=./test_home 4 4 - $ unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME XDG_RUNTIME_DIR 5 5 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 6 6 - $ ./xdg_example.exe 7 7 - === Cmdliner Config === 8 8 - XDG config: 9 9 - 10 10 - === XDG Directories === 11 11 - XDG directories for 'xdg_example': 12 12 - User directories: 13 13 - config: <fs:./test_home/./test_home/.config/xdg_example> [default] 14 14 - data: <fs:./test_home/./test_home/.local/share/xdg_example> [default] 15 15 - cache: <fs:./test_home/./test_home/.cache/xdg_example> [default] 16 16 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 17 17 - runtime: <none> [default] 18 18 - System directories: 19 19 - config_dirs: [<fs:/etc/xdg/xdg_example>] 20 20 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 21 21 - 22 22 - No command-line args or env vars are set, so all directories use defaults. 23 23 - Config shows empty (no overrides), and directories show [default] source. User 24 24 - directories follow XDG spec: ~/.config, ~/.local/share, ~/.cache, 25 25 - ~/.local/state. Runtime dir is <none> since XDG_RUNTIME_DIR has no default. 26 26 - System dirs use XDG spec defaults: /etc/xdg for config, /usr/{local/,}share for 27 27 - data. 28 28 - 29 29 - Test with all command line arguments specified 30 30 - $ unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME XDG_RUNTIME_DIR 31 31 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 32 32 - $ ./xdg_example.exe \ 33 33 - > --config-dir ./test-config \ 34 34 - > --data-dir ./test-data \ 35 35 - > --cache-dir ./test-cache \ 36 36 - > --state-dir ./test-state \ 37 37 - > --runtime-dir ./test-runtime 38 38 - === Cmdliner Config === 39 39 - XDG config: 40 40 - config_dir: ./test-config [cmdline] 41 41 - data_dir: ./test-data [cmdline] 42 42 - cache_dir: ./test-cache [cmdline] 43 43 - state_dir: ./test-state [cmdline] 44 44 - runtime_dir: ./test-runtime [cmdline] 45 45 - 46 46 - === XDG Directories === 47 47 - XDG directories for 'xdg_example': 48 48 - User directories: 49 49 - config: <fs:./test_home/./test-config> [cmdline] 50 50 - data: <fs:./test_home/./test-data> [cmdline] 51 51 - cache: <fs:./test_home/./test-cache> [cmdline] 52 52 - state: <fs:./test_home/./test-state> [cmdline] 53 53 - runtime: <fs:./test_home/./test-runtime> [cmdline] 54 54 - System directories: 55 55 - config_dirs: [<fs:/etc/xdg/xdg_example>] 56 56 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 57 57 - 58 58 - All user directories are overridden by command-line arguments, showing 59 59 - [cmdline] as the source. The config section shows all overrides with their 60 60 - values and [cmdline] sources. System directories remain at their defaults since 61 61 - they cannot be overridden by user directories command-line options. 62 62 - 63 63 - Test with environment variables (app-specific) 64 64 - $ XDG_EXAMPLE_CONFIG_DIR=./env-config \ 65 65 - > XDG_EXAMPLE_DATA_DIR=./env-data \ 66 66 - > XDG_EXAMPLE_CACHE_DIR=./env-cache \ 67 67 - > XDG_EXAMPLE_STATE_DIR=./env-state \ 68 68 - > XDG_EXAMPLE_RUNTIME_DIR=./env-runtime \ 69 69 - > ./xdg_example.exe 70 70 - === Cmdliner Config === 71 71 - XDG config: 72 72 - config_dir: ./env-config [env(XDG_EXAMPLE_CONFIG_DIR)] 73 73 - data_dir: ./env-data [env(XDG_EXAMPLE_DATA_DIR)] 74 74 - cache_dir: ./env-cache [env(XDG_EXAMPLE_CACHE_DIR)] 75 75 - state_dir: ./env-state [env(XDG_EXAMPLE_STATE_DIR)] 76 76 - runtime_dir: ./env-runtime [env(XDG_EXAMPLE_RUNTIME_DIR)] 77 77 - 78 78 - === XDG Directories === 79 79 - XDG directories for 'xdg_example': 80 80 - User directories: 81 81 - config: <fs:./test_home/./env-config> [env(XDG_EXAMPLE_CONFIG_DIR)] 82 82 - data: <fs:./test_home/./env-data> [env(XDG_EXAMPLE_DATA_DIR)] 83 83 - cache: <fs:./test_home/./env-cache> [env(XDG_EXAMPLE_CACHE_DIR)] 84 84 - state: <fs:./test_home/./env-state> [env(XDG_EXAMPLE_STATE_DIR)] 85 85 - runtime: <fs:./test_home/./env-runtime> [env(XDG_EXAMPLE_RUNTIME_DIR)] 86 86 - System directories: 87 87 - config_dirs: [<fs:/etc/xdg/xdg_example>] 88 88 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 89 89 - 90 90 - App-specific environment variables (XDG_EXAMPLE_*) override the defaults. The 91 91 - source correctly shows [env(XDG_EXAMPLE_*)] for each variable. These 92 92 - app-specific variables take precedence over XDG standard variables when both 93 93 - are available, allowing per-application customization. 94 94 - 95 95 - Test with standard XDG environment variables: 96 96 - 97 97 - $ XDG_CONFIG_HOME=/tmp/xdge/xdg-config \ 98 98 - > XDG_DATA_HOME=/tmp/xdge/xdg-data \ 99 99 - > XDG_CACHE_HOME=/tmp/xdge/xdg-cache \ 100 100 - > XDG_STATE_HOME=/tmp/xdge/xdg-state \ 101 101 - > XDG_RUNTIME_DIR=/tmp/xdge/xdg-runtime \ 102 102 - > ./xdg_example.exe 103 103 - === Cmdliner Config === 104 104 - XDG config: 105 105 - config_dir: /tmp/xdge/xdg-config [env(XDG_CONFIG_HOME)] 106 106 - data_dir: /tmp/xdge/xdg-data [env(XDG_DATA_HOME)] 107 107 - cache_dir: /tmp/xdge/xdg-cache [env(XDG_CACHE_HOME)] 108 108 - state_dir: /tmp/xdge/xdg-state [env(XDG_STATE_HOME)] 109 109 - runtime_dir: /tmp/xdge/xdg-runtime [env(XDG_RUNTIME_DIR)] 110 110 - 111 111 - === XDG Directories === 112 112 - XDG directories for 'xdg_example': 113 113 - User directories: 114 114 - config: <fs:/tmp/xdge/xdg-config> [env(XDG_CONFIG_HOME)] 115 115 - data: <fs:/tmp/xdge/xdg-data> [env(XDG_DATA_HOME)] 116 116 - cache: <fs:/tmp/xdge/xdg-cache> [env(XDG_CACHE_HOME)] 117 117 - state: <fs:/tmp/xdge/xdg-state> [env(XDG_STATE_HOME)] 118 118 - runtime: <fs:/tmp/xdge/xdg-runtime> [env(XDG_RUNTIME_DIR)] 119 119 - System directories: 120 120 - config_dirs: [<fs:/etc/xdg/xdg_example>] 121 121 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 122 122 - 123 123 - Standard XDG environment variables (XDG_*_HOME, XDG_RUNTIME_DIR) override the 124 124 - defaults. The source correctly shows [env(XDG_*)] for each variable. Note that 125 125 - the user directories use the raw paths from env vars (not app-specific subdirs) 126 126 - since XDG_CONFIG_HOME etc. are intended to be the base directories for the 127 127 - user. 128 128 - 129 129 - Test command line overrides environment variables: 130 130 - 131 131 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 132 132 - $ XDG_EXAMPLE_CONFIG_DIR=./env-config \ 133 133 - > ./xdg_example.exe --config-dir ./cli-config 134 134 - === Cmdliner Config === 135 135 - XDG config: 136 136 - config_dir: ./cli-config [cmdline] 137 137 - 138 138 - === XDG Directories === 139 139 - XDG directories for 'xdg_example': 140 140 - User directories: 141 141 - config: <fs:./test_home/./cli-config> [cmdline] 142 142 - data: <fs:./test_home/./test_home/.local/share/xdg_example> [default] 143 143 - cache: <fs:./test_home/./test_home/.cache/xdg_example> [default] 144 144 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 145 145 - runtime: <none> [default] 146 146 - System directories: 147 147 - config_dirs: [<fs:/etc/xdg/xdg_example>] 148 148 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 149 149 - 150 150 - Command-line arguments have highest precedence, overriding environment 151 151 - variables. Only config_dir is shown in the config section since it is the only 152 152 - one explicitly set. The config_dir shows [cmdline] source while other 153 153 - directories fall back to defaults, demonstrating the precedence hierarchy: of 154 154 - cmdline then app env vars then XDG env vars then defaults. 155 155 - 156 156 - Test mixed environment variable precedence (app-specific overrides XDG 157 157 - standard): 158 158 - 159 159 - $ export HOME=./test_home 160 160 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 161 161 - $ XDG_CONFIG_HOME=/tmp/xdge/xdg-config \ 162 162 - > XDG_EXAMPLE_CONFIG_DIR=./app-config \ 163 163 - > XDG_DATA_HOME=/tmp/xdge/xdg-data \ 164 164 - > XDG_EXAMPLE_DATA_DIR=./app-data \ 165 165 - > ./xdg_example.exe 166 166 - === Cmdliner Config === 167 167 - XDG config: 168 168 - config_dir: ./app-config [env(XDG_EXAMPLE_CONFIG_DIR)] 169 169 - data_dir: ./app-data [env(XDG_EXAMPLE_DATA_DIR)] 170 170 - 171 171 - === XDG Directories === 172 172 - XDG directories for 'xdg_example': 173 173 - User directories: 174 174 - config: <fs:./test_home/./app-config> [env(XDG_EXAMPLE_CONFIG_DIR)] 175 175 - data: <fs:./test_home/./app-data> [env(XDG_EXAMPLE_DATA_DIR)] 176 176 - cache: <fs:./test_home/./test_home/.cache/xdg_example> [default] 177 177 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 178 178 - runtime: <none> [default] 179 179 - System directories: 180 180 - config_dirs: [<fs:/etc/xdg/xdg_example>] 181 181 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 182 182 - 183 183 - Demonstrates app-specific environment variables taking precedence over XDG 184 184 - standard ones. Both XDG_CONFIG_HOME and XDG_EXAMPLE_CONFIG_DIR are set, but the 185 185 - app-specific one wins. Same for data directories. Cache, state, and runtime 186 186 - fall back to defaults since no variables are set for them. 187 187 - 188 188 - Test partial environment variable override: 189 189 - 190 190 - $ export HOME=./test_home 191 191 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 192 192 - $ XDG_EXAMPLE_CONFIG_DIR=./app-config \ 193 193 - > XDG_DATA_HOME=/tmp/xdge/xdg-data \ 194 194 - > XDG_CACHE_HOME=/tmp/xdge/xdg-cache \ 195 195 - > ./xdg_example.exe 196 196 - === Cmdliner Config === 197 197 - XDG config: 198 198 - config_dir: ./app-config [env(XDG_EXAMPLE_CONFIG_DIR)] 199 199 - data_dir: /tmp/xdge/xdg-data [env(XDG_DATA_HOME)] 200 200 - cache_dir: /tmp/xdge/xdg-cache [env(XDG_CACHE_HOME)] 201 201 - 202 202 - === XDG Directories === 203 203 - XDG directories for 'xdg_example': 204 204 - User directories: 205 205 - config: <fs:./test_home/./app-config> [env(XDG_EXAMPLE_CONFIG_DIR)] 206 206 - data: <fs:/tmp/xdge/xdg-data> [env(XDG_DATA_HOME)] 207 207 - cache: <fs:/tmp/xdge/xdg-cache> [env(XDG_CACHE_HOME)] 208 208 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 209 209 - runtime: <none> [default] 210 210 - System directories: 211 211 - config_dirs: [<fs:/etc/xdg/xdg_example>] 212 212 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 213 213 - 214 214 - Shows mixed sources working together. Config uses app-specific env var (highest 215 215 - priority among env vars), data and cache use XDG standard env vars (no 216 216 - app-specific ones set), and state uses default (no env vars set). Each 217 217 - directory gets its value from the highest-priority available source. 218 218 - 219 219 - Test command line overrides mixed environment variables: 220 220 - 221 221 - $ export HOME=./test_home 222 222 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 223 223 - $ XDG_CONFIG_HOME=/tmp/xdge/xdg-config \ 224 224 - > XDG_EXAMPLE_CONFIG_DIR=./app-config \ 225 225 - > ./xdg_example.exe --config-dir ./cli-config 226 226 - === Cmdliner Config === 227 227 - XDG config: 228 228 - config_dir: ./cli-config [cmdline] 229 229 - 230 230 - === XDG Directories === 231 231 - XDG directories for 'xdg_example': 232 232 - User directories: 233 233 - config: <fs:./test_home/./cli-config> [cmdline] 234 234 - data: <fs:./test_home/./test_home/.local/share/xdg_example> [default] 235 235 - cache: <fs:./test_home/./test_home/.cache/xdg_example> [default] 236 236 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 237 237 - runtime: <none> [default] 238 238 - System directories: 239 239 - config_dirs: [<fs:/etc/xdg/xdg_example>] 240 240 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 241 241 - 242 242 - Command-line argument overrides both types of environment variables. Even 243 243 - though both XDG_CONFIG_HOME and XDG_EXAMPLE_CONFIG_DIR are set, the 244 244 - --config-dir flag takes precedence and shows [cmdline] source. Other 245 245 - directories fall back to defaults since no other command-line args are 246 246 - provided. 247 247 - 248 248 - Test empty environment variable handling: 249 249 - $ export HOME=./test_home 250 250 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 251 251 - $ XDG_EXAMPLE_CONFIG_DIR="" \ 252 252 - > XDG_CONFIG_HOME=/tmp/xdge/xdg-config \ 253 253 - > ./xdg_example.exe 254 254 - === Cmdliner Config === 255 255 - XDG config: 256 256 - config_dir: /tmp/xdge/xdg-config [env(XDG_CONFIG_HOME)] 257 257 - 258 258 - === XDG Directories === 259 259 - XDG directories for 'xdg_example': 260 260 - User directories: 261 261 - config: <fs:/tmp/xdge/xdg-config> [env(XDG_CONFIG_HOME)] 262 262 - data: <fs:./test_home/./test_home/.local/share/xdg_example> [default] 263 263 - cache: <fs:./test_home/./test_home/.cache/xdg_example> [default] 264 264 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 265 265 - runtime: <none> [default] 266 266 - System directories: 267 267 - config_dirs: [<fs:/etc/xdg/xdg_example>] 268 268 - data_dirs: [<fs:/usr/local/share/xdg_example>; <fs:/usr/share/xdg_example>] 269 269 - 270 270 - When an app-specific env var is empty (""), it falls back to the XDG standard 271 271 - variable. XDG_EXAMPLE_CONFIG_DIR="" is ignored, so XDG_CONFIG_HOME is used 272 272 - instead, correctly showing [env(XDG_CONFIG_HOME)] as the source. This behavior 273 273 - ensures that empty app-specific variables do not override useful XDG standard 274 274 - settings. 275 275 - 276 276 - Test system directory environment variables: 277 277 - 278 278 - $ export HOME=./test_home 279 279 - $ unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME XDG_RUNTIME_DIR 280 280 - $ XDG_CONFIG_DIRS=/tmp/xdge/sys1:/tmp/xdge/sys2 \ 281 281 - > XDG_DATA_DIRS=/tmp/xdge/data1:/tmp/xdge/data2 \ 282 282 - > ./xdg_example.exe 283 283 - === Cmdliner Config === 284 284 - XDG config: 285 285 - 286 286 - === XDG Directories === 287 287 - XDG directories for 'xdg_example': 288 288 - User directories: 289 289 - config: <fs:./test_home/./test_home/.config/xdg_example> [default] 290 290 - data: <fs:./test_home/./test_home/.local/share/xdg_example> [default] 291 291 - cache: <fs:./test_home/./test_home/.cache/xdg_example> [default] 292 292 - state: <fs:./test_home/./test_home/.local/state/xdg_example> [default] 293 293 - runtime: <none> [default] 294 294 - System directories: 295 295 - config_dirs: [<fs:/tmp/xdge/sys1/xdg_example>; 296 296 - <fs:/tmp/xdge/sys2/xdg_example>] 297 297 - data_dirs: [<fs:/tmp/xdge/data1/xdg_example>; 298 298 - <fs:/tmp/xdge/data2/xdg_example>] 299 299 - 300 300 - XDG_CONFIG_DIRS and XDG_DATA_DIRS environment variables override the default 301 301 - system directories. The colon-separated paths are parsed and the app name is 302 302 - appended to each path. User directories remain at defaults since no user-level 303 303 - overrides are provided. System directory env vars only affect the system 304 304 - directories, not user directories. 305 305 - 306 306 - Test _path functions do not create directories but can access files within them: 307 307 - 308 308 - $ export HOME=/tmp/xdge/xdg_path_test 309 309 - $ mkdir -p /tmp/xdge/xdg_path_test 310 310 - $ unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME XDG_RUNTIME_DIR 311 311 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 312 312 - Create config subdirectory manually and write a test file: 313 313 - $ mkdir -p "/tmp/xdge/xdg_path_test/.config/path_test/profiles" 314 314 - $ echo "test profile content" > "/tmp/xdge/xdg_path_test/.config/path_test/profiles/default.json" 315 315 - Create data subdirectory manually and write a test file: 316 316 - $ mkdir -p "/tmp/xdge/xdg_path_test/.local/share/path_test/databases" 317 317 - $ echo "test database content" > "/tmp/xdge/xdg_path_test/.local/share/path_test/databases/main.db" 318 318 - Create cache subdirectory manually and write a test file: 319 319 - $ mkdir -p "/tmp/xdge/xdg_path_test/.cache/path_test/thumbnails" 320 320 - $ echo "test cache content" > "/tmp/xdge/xdg_path_test/.cache/path_test/thumbnails/thumb1.png" 321 321 - Create state subdirectory manually and write a test file: 322 322 - $ mkdir -p "/tmp/xdge/xdg_path_test/.local/state/path_test/logs" 323 323 - $ echo "test log content" > "/tmp/xdge/xdg_path_test/.local/state/path_test/logs/app.log" 324 324 - 325 325 - Now test that we can read the files through the XDG _path functions: 326 326 - $ ./test_paths.exe 327 327 - config file content: test profile content 328 328 - data file content: test database content 329 329 - cache file content: test cache content 330 330 - state file content: test log content 331 331 - 332 332 - This test verifies that the _path functions return correct paths that can be used to access 333 333 - files within XDG subdirectories, without the functions automatically creating those directories. 334 334 - 335 335 - Test path resolution with --show-paths: 336 336 - 337 337 - Test with a preset HOME to verify correct path resolution: 338 338 - $ export HOME=./home_testuser 339 339 - $ unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME XDG_RUNTIME_DIR 340 340 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 341 341 - $ ./xdg_example.exe --show-paths 342 342 - config_dir: ./home_testuser/./home_testuser/.config/xdg_example 343 343 - data_dir: ./home_testuser/./home_testuser/.local/share/xdg_example 344 344 - cache_dir: ./home_testuser/./home_testuser/.cache/xdg_example 345 345 - state_dir: ./home_testuser/./home_testuser/.local/state/xdg_example 346 346 - runtime_dir: <none> 347 347 - config_dirs: /etc/xdg/xdg_example 348 348 - data_dirs: /usr/local/share/xdg_example:/usr/share/xdg_example 349 349 - 350 350 - Test with environment variables set: 351 351 - $ export HOME=./home_testuser 352 352 - $ export XDG_CONFIG_HOME=/tmp/xdge/config 353 353 - $ export XDG_DATA_HOME=/tmp/xdge/data 354 354 - $ export XDG_CACHE_HOME=/tmp/xdge/cache 355 355 - $ export XDG_STATE_HOME=/tmp/xdge/state 356 356 - $ export XDG_CONFIG_DIRS=/tmp/xdge/config1:/tmp/xdge/config2 357 357 - $ export XDG_DATA_DIRS=/tmp/xdge/data1:/tmp/xdge/data2 358 358 - $ ./xdg_example.exe --show-paths 359 359 - config_dir: /tmp/xdge/config 360 360 - data_dir: /tmp/xdge/data 361 361 - cache_dir: /tmp/xdge/cache 362 362 - state_dir: /tmp/xdge/state 363 363 - runtime_dir: <none> 364 364 - config_dirs: /tmp/xdge/config1/xdg_example:/tmp/xdge/config2/xdg_example 365 365 - data_dirs: /tmp/xdge/data1/xdg_example:/tmp/xdge/data2/xdg_example 366 366 - 367 367 - Test with command-line overrides: 368 368 - $ export HOME=./home_testuser 369 369 - $ unset XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME XDG_RUNTIME_DIR 370 370 - $ unset XDG_CONFIG_DIRS XDG_DATA_DIRS 371 371 - $ ./xdg_example.exe --show-paths --config-dir ./override/config --data-dir ./override/data 372 372 - config_dir: ./home_testuser/./override/config 373 373 - data_dir: ./home_testuser/./override/data 374 374 - cache_dir: ./home_testuser/./home_testuser/.cache/xdg_example 375 375 - state_dir: ./home_testuser/./home_testuser/.local/state/xdg_example 376 376 - runtime_dir: <none> 377 377 - config_dirs: /etc/xdg/xdg_example 378 378 - data_dirs: /usr/local/share/xdg_example:/usr/share/xdg_example 379 379 -

-39

xdge/test/xdg_example.ml

reviewed

··· 1 1 - (*--------------------------------------------------------------------------- 2 2 - Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved. 3 3 - SPDX-License-Identifier: ISC 4 4 - ---------------------------------------------------------------------------*) 5 5 - 6 6 - let run (xdg, cfg) = 7 7 - Fmt.pr "%a@.%a@.@.%a@.%a@." 8 8 - Fmt.(styled `Bold string) 9 9 - "=== Cmdliner Config ===" Xdge.Cmd.pp cfg 10 10 - Fmt.(styled `Bold string) 11 11 - "=== XDG Directories ===" 12 12 - (Xdge.pp ~brief:false ~sources:true) 13 13 - xdg 14 14 - 15 15 - open Cmdliner 16 16 - 17 17 - let () = 18 18 - Fmt.set_style_renderer Fmt.stdout `Ansi_tty; 19 19 - let app_name = "xdg_example" in 20 20 - let doc = 21 21 - "Example program demonstrating XDG directory selection with Cmdliner" 22 22 - in 23 23 - let man = 24 24 - [ 25 25 - `S Manpage.s_description; 26 26 - `P 27 27 - "This example shows how to use the Xdge library with Cmdliner to \ 28 28 - handle XDG Base Directory Specification paths with command-line and \ 29 29 - environment variable overrides."; 30 30 - `S Manpage.s_environment; 31 31 - `P (Xdge.Cmd.env_docs app_name); 32 32 - ] 33 33 - in 34 34 - let info = Cmdliner.Cmd.info "xdg_example" ~version:"1.0" ~doc ~man in 35 35 - Eio_main.run @@ fun env -> 36 36 - let create_xdg_term = Xdge.Cmd.term app_name env#fs () in 37 37 - let main_term = Term.(const run $ create_xdg_term) in 38 38 - let cmd = Cmdliner.Cmd.v info main_term in 39 39 - exit @@ Cmdliner.Cmd.eval cmd

-4

xdge/test/xdg_example.mli

reviewed

··· 1 1 - (*--------------------------------------------------------------------------- 2 2 - Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved. 3 3 - SPDX-License-Identifier: ISC 4 4 - ---------------------------------------------------------------------------*)

-28

xdge/xdge.opam

reviewed

··· 1 1 - # This file is generated by dune, edit dune-project instead 2 2 - opam-version: "2.0" 3 3 - synopsis: "XDG Base Directory Specification support for Eio" 4 4 - description: 5 5 - "This library implements the XDG Base Directory Specification with Eio capabilities to provide safe access to configuration, data, cache, state, and runtime directories. The library exposes Cmdliner terms that allow for proper environment variable overrides and command-line flags." 6 6 - maintainer: ["Anil Madhavapeddy <anil@recoil.org>"] 7 7 - authors: ["Anil Madhavapeddy"] 8 8 - license: "ISC" 9 9 - homepage: "https://tangled.sh/@anil.recoil.org/xdge" 10 10 - bug-reports: "https://tangled.sh/@anil.recoil.org/xdge/issues" 11 11 - depends: [ 12 12 - "dune" {>= "3.20"} 13 13 - "ocaml" {>= "5.1.0"} 14 14 - "eio" {>= "1.1"} 15 15 - "cmdliner" {>= "1.2.0"} 16 16 - "fmt" 17 17 - "xdg" 18 18 - "eio_main" {with-test} 19 19 - "odoc" {with-doc} 20 20 - "alcotest" {with-test & >= "1.7.0"} 21 21 - ] 22 22 - x-maintenance-intent: ["(latest)"] 23 23 - build: [ 24 24 - [ "dune" "subst" ] {dev} 25 25 - [ "dune" "build" "-p" name "-j" jobs "@install" ] 26 26 - [ "dune" "build" "-p" name "-j" jobs "runtest" ] {with-test & opam-version >= "2.2"} 27 27 - [ "dune" "build" "-p" name "-j" jobs "@doc" ] {with-doc} 28 28 - ]

-6

xdge/xdge.opam.template

reviewed

··· 1 1 - build: [ 2 2 - [ "dune" "subst" ] {dev} 3 3 - [ "dune" "build" "-p" name "-j" jobs "@install" ] 4 4 - [ "dune" "build" "-p" name "-j" jobs "runtest" ] {with-test & opam-version >= "2.2"} 5 5 - [ "dune" "build" "-p" name "-j" jobs "@doc" ] {with-doc} 6 6 - ]