Home

Awesome

Discord

Need help? Create an issue or ping @Gytis.iva in the above Discord Server.

Changing branching policy

From now on master serves as a development branch (previously staging was used for such purposes). Please use tags for stable releases of flake-utils-plus. In general, with the improvements in test harness, releases might happen more frequently. Sticking with a tagged release might offer better trade-offs going forward.

What is this flake?

Flake-utils-plus exposes a library abstraction to painlessly generate NixOS flake configurations.

The biggest design goal is to keep down the fluff. The library is meant to be easy to understand and use. It aims to be far simpler than frameworks such as DevOS (previously called nixflk).

How to use

Examples

We recommend referring to people's examples below when setting up your system.

Features of the flake

Main flake-utils-plus features (Attributes visible from flake.nix):

Documentation

Options with their example usage and description.

let
  inherit (builtins) removeAttrs;
  mkApp = utils.lib.mkApp;
  # If there is a need to get direct reference to nixpkgs - do this:
  pkgs = self.pkgs.x86_64-linux.nixpkgs;
in flake-utils-plus.lib.mkFlake {


  # `self` and `inputs` arguments are REQUIRED!
  inherit self inputs;

  # Supported systems, used for packages, apps, devShell and multiple other definitions. Defaults to `flake-utils.lib.defaultSystems`.
  supportedSystems = [ "x86_64-linux" ];


  ################
  ### channels ###
  ################

  # Configuration that is shared between all channels.
  channelsConfig = { allowBroken = true; };

  # Overlays which are applied to all channels.
  sharedOverlays = [ nur.overlay ];

  # Nixpkgs flake reference to be used in the configuration.
  # Autogenerated from `inputs` by default.
  channels.<name>.input = nixpkgs;

  # Channel specific config options.
  channels.<name>.config = { allowUnfree = true; };

  # Patches to apply on selected channel.
  channels.<name>.patches = [ ./someAwesomePatch.patch ];

  # Overlays to apply on a selected channel.
  channels.<name>.overlaysBuilder = channels: [
    (final: prev: { inherit (channels.unstable) neovim; })
  ];


  ####################
  ### hostDefaults ###
  ####################

  # Default architecture to be used for `hosts` defaults to "x86_64-linux".
  hostDefaults.system = "x86_64-linux";

  # Default modules to be passed to all hosts.
  hostDefaults.modules = [ ./module.nix ./module2 ];

  # Reference to `channels.<name>.*`, defines default channel to be used by hosts. Defaults to "nixpkgs".
  hostDefaults.channelName = "unstable";

  # Extra arguments to be passed to all modules. Merged with host's extraArgs.
  hostDefaults.extraArgs = { inherit utils inputs; foo = "foo"; };


  #############
  ### hosts ###
  #############

  # System architecture. Defaults to `defaultSystem` argument.
  hosts.<hostname>.system = "aarch64-linux";

  # <name> of the channel to be used. Defaults to `nixpkgs`;
  hosts.<hostname>.channelName = "unstable";

  # Extra arguments to be passed to the modules.
  hosts.<hostname>.extraArgs = { abc = 123; };

  # These are not part of the module system, so they can be used in `imports` lines without infinite recursion.
  hosts.<hostname>.specialArgs = { thing = "abc"; };

  # Host specific configuration.
  hosts.<hostname>.modules = [ ./configuration.nix ];

  # Flake output for configuration to be passed to. Defaults to `nixosConfigurations`.
  hosts.<hostname>.output = "darwinConfigurations";

  # System builder. Defaults to `channels.<name>.input.lib.nixosSystem`.
  hosts.<hostname>.builder = nix-darwin.lib.darwinSystem;


  #############################
  ### flake outputs builder ###
  #############################


  outputsBuilder = channels: {
    # Evaluates to `apps.<system>.custom-neovim  = utils.lib.mkApp { drv = ...; exePath = ...; };`.
    apps = {
      custom-neovim = mkApp {
        drv = fancy-neovim;
        exePath = "/bin/nvim";
      };
    };

    # Evaluates to `packages.<system>.package-from-overlays = <unstable-nixpkgs-reference>.package-from-overlays`.
    packages = { inherit (channels.unstable) package-from-overlays; };

    # Evaluates to `apps.<system>.firefox  = utils.lib.mkApp { drv = ...; };`.
    defaultApp = mkApp { drv = channels.nixpkgs.firefox; };

    # Evaluates to `defaultPackage.<system>.neovim = <nixpkgs-channel-reference>.neovim`.
    defaultPackage = channels.nixpkgs.neovim;

    # Evaluates to `devShell.<system> = <nixpkgs-channel-reference>.mkShell { name = "devShell"; };`.
    devShell = channels.nixpkgs.mkShell { name = "devShell"; };
  };


  #########################################################
  ### All other properties are passed down to the flake ###
  #########################################################

  checks.x86_64-linux.someCheck = pkgs.hello;
  packages.x86_64-linux.somePackage = pkgs.hello;
  overlay = import ./overlays;
  abc = 132;

}