{"id":13611144,"url":"https://github.com/numtide/flake-utils","last_synced_at":"2025-05-14T15:05:39.191Z","repository":{"id":38079036,"uuid":"254872371","full_name":"numtide/flake-utils","owner":"numtide","description":"Pure Nix flake utility functions [maintainer=@zimbatm]","archived":false,"fork":false,"pushed_at":"2024-11-13T21:27:18.000Z","size":113,"stargazers_count":1356,"open_issues_count":23,"forks_count":82,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-05-08T03:59:32.126Z","etag":null,"topics":["flake","nix","nix-flake"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/numtide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2020-04-11T13:21:34.000Z","updated_at":"2025-05-07T14:50:51.000Z","dependencies_parsed_at":"2024-01-29T07:28:04.394Z","dependency_job_id":"de0af74b-6665-4ab7-8c92-98cbbabf4217","html_url":"https://github.com/numtide/flake-utils","commit_stats":{"total_commits":88,"total_committers":29,"mean_commits":"3.0344827586206895","dds":0.6363636363636364,"last_synced_commit":"b1d9ab70662946ef0850d488da1c9019f3a9752a"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fflake-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fflake-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fflake-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/numtide%2Fflake-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/numtide","download_url":"https://codeload.github.com/numtide/flake-utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254168799,"owners_count":22026206,"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":["flake","nix","nix-flake"],"created_at":"2024-08-01T19:01:52.189Z","updated_at":"2025-05-14T15:05:39.149Z","avatar_url":"https://github.com/numtide.png","language":"Nix","funding_links":[],"categories":["Nix","Development","others"],"sub_categories":["Discovery"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# flake-utils\n\n\u003cimg src=\"flake-utils.svg\" height=\"150\"/\u003e\n\n**Pure Nix flake utility functions.**\n\n*A \u003ca href=\"https://numtide.com/\"\u003enumtide\u003c/a\u003e project.*\n\n\u003cp\u003e\n\u003ca href=\"https://github.com/numtide/flake-utils/actions/workflows/nix.yml\"\u003e\u003cimg src=\"https://github.com/numtide/flake-utils/actions/workflows/nix.yml/badge.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://app.element.io/#/room/#home:numtide.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Support-%23numtide-blue\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\nThe goal of this project is to build a collection of pure Nix functions that don't\ndepend on nixpkgs, and that are useful in the context of writing other Nix\nflakes.\n\n## Usage\n\n### `system :: { system = system, ... }`\n\nA map from system to system built from `allSystems`:\n```nix\nsystem = {\n  x86_64-linux = \"x86_64-linux\";\n  x86_64-darwin = \"x86_64-darwin\";\n  ...\n}\n```\nIt's mainly useful to\ndetect typos and auto-complete if you use [rnix-lsp](https://github.com/nix-community/rnix-lsp).\n\nEg: instead of typing `\"x86_64-linux\"`, use `system.x86_64-linux`.\n\n\n### `allSystems :: [\u003csystem\u003e]`\n\nA list of all systems defined in nixpkgs. For a smaller list see `defaultSystems`.\n\n### `defaultSystems :: [\u003csystem\u003e]`\n\nThe list of systems to use in `eachDefaultSystem` and `simpleFlake`.\n\nThe default values are `[\"x86_64-linux\" \"aarch64-linux\" \"x86_64-darwin\" \"aarch64-darwin\"]`.\n\nIt's possible to override and control that list by changing the `systems` input of this flake.\n\nEg (in your `flake.nix`):\n\n```nix\n{\n  # 1. Defined a \"systems\" inputs that maps to only [\"x86_64-linux\"]\n  inputs.systems.url = \"github:nix-systems/x86_64-linux\";\n\n  inputs.flake-utils.url = \"github:numtide/flake-utils\";\n  # 2. Override the flake-utils default to your version\n  inputs.flake-utils.inputs.systems.follows = \"systems\";\n\n  outputs = { self, flake-utils, ... }:\n    # Now eachDefaultSystem is only using [\"x86_64-linux\"], but this list can also\n    # further be changed by users of your flake.\n    flake-utils.lib.eachDefaultSystem (system: {\n      # ...\n    });\n}\n```\n\nFor more details in this pattern, see: \u003chttps://github.com/nix-systems/nix-systems\u003e.\n\n### `eachSystem :: [\u003csystem\u003e] -\u003e (\u003csystem\u003e -\u003e attrs)`\n\nA common case is to build the same structure for each system. Instead of\nbuilding the hierarchy manually or per prefix, iterate over each systems and\nthen re-build the hierarchy.\n\nEg:\n\n```nix\neachSystem [ system.x86_64-linux ] (system: { hello = 42; })\n# =\u003e { hello = { x86_64-linux = 42; }; }\neachSystem allSystems (system: { hello = 42; })\n# =\u003e {\n   hello.aarch64-darwin = 42,\n   hello.aarch64-genode = 42,\n   hello.aarch64-linux = 42,\n   ...\n   hello.x86_64-redox = 42,\n   hello.x86_64-solaris = 42,\n   hello.x86_64-windows = 42\n}\n```\n\n### `eachSystemPassThrough :: [\u003csystem\u003e] -\u003e (\u003csystem\u003e -\u003e attrs)`\n\nUnlike `eachSystem`, this function does not inject the `${system}` key by merely\nproviding the system argument to the function.\n\n### `eachDefaultSystem :: (\u003csystem\u003e -\u003e attrs)`\n\n`eachSystem` pre-populated with `defaultSystems`.\n\n#### Example\n\n[$ examples/each-system/flake.nix](examples/each-system/flake.nix) as nix\n```nix\n{\n  description = \"Flake utils demo\";\n\n  inputs.flake-utils.url = \"github:numtide/flake-utils\";\n\n  outputs = { self, nixpkgs, flake-utils }:\n    flake-utils.lib.eachDefaultSystem (system:\n      let pkgs = nixpkgs.legacyPackages.${system}; in\n      {\n        packages = rec {\n          hello = pkgs.hello;\n          default = hello;\n        };\n        apps = rec {\n          hello = flake-utils.lib.mkApp { drv = self.packages.${system}.hello; };\n          default = hello;\n        };\n      }\n    );\n}\n```\n\n### `eachDefaultSystemPassThrough :: (\u003csystem\u003e -\u003e attrs)`\n\n`eachSystemPassThrough` pre-populated with `defaultSystems`.\n\n#### Example\n\n```nix\ninputs.flake-utils.lib.eachDefaultSystem (system: {\n  checks./*\u003cSYSTEM\u003e.*/\"\u003cCHECK\u003e\" = /* ... */;\n  devShells./*\u003cSYSTEM\u003e.*/\"\u003cDEV_SHELL\u003e\" = /* ... */;\n  packages./*\u003cSYSTEM\u003e.*/\"\u003cPACKAGE\u003e\" = /* ... */;\n})\n// inputs.flake-utils.lib.eachDefaultSystemPassThrough (system: {\n  homeConfigurations.\"\u003cHOME_CONFIGURATION\u003e\" = /* ... */;\n  nixosConfigurations.\"\u003cNIXOS_CONFIGURATION\u003e\" = /* ... */;\n})\n```\n\n### `meld :: attrs -\u003e [ path ] -\u003e attrs`\n\nMeld merges subflakes using common inputs.  Useful when you want to\nsplit up a large flake with many different components into more\nmanageable parts.\n\n### `mkApp { drv, name ? drv.pname or drv.name, exePath ? drv.passthru.exePath or \"/bin/${name}\"`\n\nA small utility that builds the structure expected by the special `apps` and `defaultApp` prefixes.\n\n\n### `flattenTree :: attrs -\u003e attrs`\n\nNix flakes insists on having a flat attribute set of derivations in\nvarious places like the `packages` and `checks` attributes.\n\nThis function traverses a tree of attributes (by respecting\n[recurseIntoAttrs](https://noogle.dev/f/lib/recurseIntoAttrs)) and only returns their derivations, with a flattened\nkey-space.\n\nEg:\n```nix\nflattenTree { hello = pkgs.hello; gitAndTools = pkgs.gitAndTools }\n```\nReturns:\n\n```nix\n{\n  hello = «derivation»;\n  \"gitAndTools/git\" = «derivation»;\n  \"gitAndTools/hub\" = «derivation»;\n  # ...\n}\n```\n\n### `simpleFlake :: attrs -\u003e attrs`\n\nThis function should be useful for most common use-cases where you have a\nsimple flake that builds a package. It takes nixpkgs and a bunch of other\nparameters and outputs a value that is compatible as a flake output.\n\nInput:\n```nix\n{\n  # pass an instance of self\n  self\n, # pass an instance of the nixpkgs flake\n  nixpkgs\n, # we assume that the name maps to the project name, and also that the\n  # overlay has an attribute with the `name` prefix that contains all of the\n  # project's packages.\n  name\n, # nixpkgs config\n  config ? { }\n, # pass either a function or a file\n  overlay ? null\n, # use this to load other flakes overlays to supplement nixpkgs\n  preOverlays ? [ ]\n, # maps to the devShell output. Pass in a shell.nix file or function.\n  shell ? null\n, # pass the list of supported systems\n  systems ? [ \"x86_64-linux\" \"aarch64-linux\" \"x86_64-darwin\" \"aarch64-darwin\" ]\n}: null\n```\n\n#### Example\n\nHere is how it looks like in practice:\n\n[$ examples/simple-flake/flake.nix](examples/simple-flake/flake.nix) as nix\n```nix\n{\n  description = \"Flake utils demo\";\n\n  inputs.flake-utils.url = \"github:numtide/flake-utils\";\n\n  outputs = { self, nixpkgs, flake-utils }:\n    flake-utils.lib.simpleFlake {\n      inherit self nixpkgs;\n      name = \"simple-flake\";\n      overlay = ./overlay.nix;\n      shell = ./shell.nix;\n    };\n}\n```\n\n## Commercial support\n\nLooking for help or customization?\n\nGet in touch with Numtide to get a quote. We make it easy for companies to\nwork with Open Source projects: \u003chttps://numtide.com/contact\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtide%2Fflake-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumtide%2Fflake-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumtide%2Fflake-utils/lists"}