{"id":16335321,"url":"https://github.com/infinisil/nix-xdg","last_synced_at":"2025-03-22T23:32:16.067Z","repository":{"id":175134710,"uuid":"109542602","full_name":"infinisil/nix-xdg","owner":"infinisil","description":"[WIP] Nix overlay for making programs xdg compliant","archived":false,"fork":false,"pushed_at":"2017-12-01T05:24:48.000Z","size":20,"stargazers_count":21,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-18T15:47:22.383Z","etag":null,"topics":["binary-wrapper","home-manager","nix","nixos","xdg-compliance"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infinisil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-05T01:17:53.000Z","updated_at":"2025-02-03T20:24:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"1ed38ad4-7cd0-4221-816a-4750db421044","html_url":"https://github.com/infinisil/nix-xdg","commit_stats":null,"previous_names":["infinisil/nix-xdg"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinisil%2Fnix-xdg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinisil%2Fnix-xdg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinisil%2Fnix-xdg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinisil%2Fnix-xdg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infinisil","download_url":"https://codeload.github.com/infinisil/nix-xdg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245036112,"owners_count":20550662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-wrapper","home-manager","nix","nixos","xdg-compliance"],"created_at":"2024-10-10T23:40:49.305Z","updated_at":"2025-03-22T23:32:15.752Z","avatar_url":"https://github.com/infinisil.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [WIP] Nix overlay for making programs xdg compliant\n\nThis repo contains a nixos module (also usable with home-manager) for making\nprograms xdg compliant, by wrapping the binaries with certain environment\nvariables set or certains flags passed. Created the first draft in early 2017,\nbut only just got it to a usable state, motivated by\nhttps://github.com/rycee/home-manager/issues/95.\n\nAll of it is done with a manual\nspecification for each program, which looks something like this:\n\n```nix\n{\n  wget.flags = { cache }: \"--hsts-file=${cache}/hsts\";\n  less.env.ZDOTDIR = { config }: config;\n}\n```\n\nThis spec defines that all binaries in the wget package be wrapped with the\n\"--hsts-file\" flag set to a file in the packages cache directory, which is\n`${XDG_CACHE_HOME:-$HOME/.cache}/wget` in this case, evaluating to\n`~/.cache/wget` at runtime if `XDG_CACHE_HOME` isn't set. Second, all binaries\nin the zsh package be wrapped with `ZDOTDIR` set to the packages config\ndirectory, which is `${XDG_CONFIG_HOME:-$HOME/.config}/zsh`. Similarly, you can\nuse a `data` argument for getting\n`${XDG_DATA_HOME:-$HOME/.local/share}/\u003cname\u003e`.\n\nThe `specs.nix` file contains some more examples. Also supported is wrapping\nspecific binaries (for packages containing multiple binaries) and changing the\nfolder name of the package directories (maybe useful for different versions). By\ndefault, the top-level attributes name (`\"wget\"` and `\"less\"` in the above\nexample is used to get the package to wrap, this can be made explicit with\n`package` attribute. The following example demonstrates these features (along\nwith some others):\n\n```nix\n{\n  myHello = {\n    # Use the hello package, since `pkgs.myHello` doesn't exist\n    package = pkgs.hello;\n\n    # This will make the config argument be\n    # \"${XDG_CONFIG_HOME:-$HOME/.config}/hithere\", and similarily for cache and\n    # data\n    xdgName = \"hithere\";\n\n    # Wrapping the hello binary only\n    bin.hello.env.HELLO_DATA = { data }: data;\n\n    # Such a function can occur anywhere _within_ the packages spec, and the\n    arguments will contain the packages directories\n    env = { config }: {\n      # This will apply for all binaries except the hello one, since HELLO_DATA\n      # is explicitly specified for it already.\n      HELLO_DATA = \"$HOME/.hello\";\n      HELLO_CONFIG = config;\n    };\n  };\n}\n```\n\n# How to use\n\nImport the `module.nix` file in your NixOS or home-manager configuration, by\neither cloning this repository and adding\n\n```nix\n{\n  imports = [\n    ~/path/to/module.nix\n  ];\n}\n```\n\nor with nix directly:\n\n```nix\n{\n  imports = [\n    (builtins.fetchTarBall https://github.com/Infinisil/xdg-nix/archive/master.tar.gz)\n  ];\n}\n```\n\nBy default no specs are added.\n\n## Adding specs\n\nYou can add specifications by declaring them in the `xdgSpec` option like\n\n```nix\n{\n  xdgSpec = {\n    wget.flags = { cache }: \"--hsts-file=${cache}/hsts\";\n  };\n}\n```\n\nAll attributes in the `specs.nix` file are available through an optional\nargument. For example you can include the base set like this:\n\n```nix\n{\n  xdgSpec = specs: specs.base;\n}\n```\n\n## Using packages\n\nTo actually use the wrapped package, you'll have to specify it somewhere in your\nnixos / home-manager config, such as\n\n```nix\n{\n  # NixOS\n  environment.systemPackages = with pkgs; [ wget ];\n\n  # home-manager\n  home.packages = with pkgs; [ wget ];\n}\n```\n\n\n## Avoiding rebuild of dependent packages\n\nSince the wrapped packages differ, other packages dependent on these will be\nrebuilt when adding/changing the spec, which is unavoidable if you really want\nto use overlays and have the changes propagate.\nTo avoid having to do that, you can include the package in your\npackages directly, which is mostly just what you need:\n\n```nix\n{ config, ... }:\nlet\n  xdg = import \u003cnixpkgs\u003e {\n    overlays = [ (config.lib.xdg.xdgOverlay {\n      specs = foo: foo.all;\n    })];\n  };\nin {\n  # NixOS\n  environment.systemPackages = with xdg; [ curl ];\n\n  # home-manager\n  home.packages = with xdg; [ curl ];\n}\n```\n\n# ToDo\n\n- Split into more files, add default.nix, support for just importing the\n  functions, add overlay.nix\n- Overlay rebuilds a lot, but most often you just want changes in the user\n  profiles packages anyways -\u003e what to use instead of an overlay to not make it\n  ugly?\n- How to use only specific packages wrapped easily?\n- Potential home-manager integration, see https://github.com/rycee/home-manager/issues/95\n- Go through https://wiki.archlinux.org/index.php/XDG_Base_Directory_support and\n\tcheck if there are any problems\n- Maybe add XDG_RUNTIME_DIR\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinisil%2Fnix-xdg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfinisil%2Fnix-xdg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinisil%2Fnix-xdg/lists"}