|
||
---|---|---|
.github | ||
examples | ||
lib | ||
tests | ||
.gitignore | ||
devShell.nix | ||
flake.lock | ||
flake.nix | ||
LICENSE | ||
README.md |
Need help? Create an issue or ping @Gytis#0001 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.
Please note, while 1.2.0 retains backwards compatibility, 1.3.0 is the same version with all backwards compatibility removed.
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
):
- Extends flake-utils. Everything exported by fu can be used from this flake.
lib.mkFlake { ... }
- Clean and pleasant to use flakes abstraction.- Option
nix.generateRegistryFromInputs
- Generatesnix.registry
from flake inputs. - Option
nix.generateNixPathFromInputs
- Generatenix.nixPath
from available inputs. - Option
nix.linkInputs
- Symlink inputs to /etc/nix/inputs. - Simple and clean support for multiple
nixpkgs
references. nixpkgs
references patching.channelsConfig
- Config applied to allnixpkgs
references.hostDefaults
- Default configuration shared between host definitions.outputsBuilder
- Clean way to export packages/apps/etc.sharedOverlays
- Overlays applied on all imported channels.
- Option
lib.exportModules [ ./a.nix ./b.nix ]
- Generates module attribute which look like this{ a = import ./a.nix; b = import ./b.nix; }
.lib.exportOverlays channels
- Exports all overlays from channels as an appropriately namespaced attribute set. Users can instantiate with their nixpkgs version.lib.exportPackages self.overlays channels
- Similar to the overlay generator, but outputs them as packages for the platforms defined inmeta.platforms
. Unlike overlays, these packages are consistent across flakes allowing them to be cached.pkgs.fup-repl
- A package that adds a kick-ass repl. Usage:$ repl
- Loads your system repl into scope as well aspkgs
andlib
fromnixpkgs
input.$ repl /path/to/flake.nix
- Same as above but loads the specified flake.
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;
}