+1

.gitignore

··· 1 1 + _build

+1

.ocamlformat

··· 1 1 + version=0.28.1

+44

.tangled/workflows/build.yml

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

+18

LICENSE.md

··· 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 + *)

+30

dune-project

··· 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/xgde/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 (>= 0.11.0)) 28 28 + (odoc :with-doc) 29 29 + (eio_main :with-test) 30 30 + (alcotest (and :with-test (>= 1.7.0)))))

+4

lib/dune

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

+657

lib/xdge.ml

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

+428

lib/xdge.mli

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

+10

test/dune

··· 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))

+105

test/test_paths.ml

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

+379

test/xdg.t

··· 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 +

+34

test/xdg_example.ml

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

+35

xdge.opam

··· 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/xgde/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" {>= "0.11.0"} 17 17 + "odoc" {with-doc} 18 18 + "eio_main" {with-test} 19 19 + "alcotest" {with-test & >= "1.7.0"} 20 20 + ] 21 21 + build: [ 22 22 + ["dune" "subst"] {dev} 23 23 + [ 24 24 + "dune" 25 25 + "build" 26 26 + "-p" 27 27 + name 28 28 + "-j" 29 29 + jobs 30 30 + "@install" 31 31 + "@runtest" {with-test} 32 32 + "@doc" {with-doc} 33 33 + ] 34 34 + ] 35 35 + x-maintenance-intent: ["(latest)"]