mirrors/flake-parts
1
0
Fork 0
mirror of https://github.com/hercules-ci/flake-parts.git synced 2024-12-14 11:47:31 +00:00
Code Activity

Merge pull request #73 from hercules-ci/tidy-readme

Browse source 
Remove docs that have been moved to flake.parts and improved
This commit is contained in:
Robert Hensing 2022-11-14 19:36:17 +01:00 committed by GitHub
commit d591857e9d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 3 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
README.md
View file

@ -45,6 +45,8 @@ If your project does not have a flake yet:
nix flake init -t github:hercules-ci/flake-parts
```
# Migrate
Otherwise, add the input,
```
@ -75,88 +77,8 @@ See [the template](./template/default/flake.nix).
# Options Reference
See [flake.parts](https://flake.parts/options.html)
See [flake.parts options](https://flake.parts/options/flake-parts.html)
# Documentation
See [flake.parts](https://flake.parts)
# Top-level module parameters
- `config`, `options`, `lib`, ...: standard module system parameters.
- `getSystem`: function from system string to the `config` of the appropriate `perSystem`.
- `moduleWithSystem`: function that brings the `perSystem` module arguments.
This allows a module to reference the defining flake without introducing
global variables (which may conflict).
```nix
{ moduleWithSystem, ... }:
{
nixosModules.default = moduleWithSystem (
perSystem@{ config }: # NOTE: only explicit params will be in perSystem
nixos@{ ... }:
{
services.foo.package = perSystem.config.packages.foo;
imports = [ ./nixos-foo.nix ];
}
);
}
```
- `withSystem`: enter the scope of a system. Worked example:
```nix
{ withSystem, ... }:
{
# perSystem = ...;
nixosConfigurations.foo = withSystem "x86_64-linux" (ctx@{ pkgs, ... }:
pkgs.nixos ({ config, lib, packages, pkgs, ... }: {
_module.args.packages = ctx.config.packages;
imports = [ ./nixos-configuration.nix ];
services.nginx.enable = true;
environment.systemPackages = [
packages.hello
];
}));
}
```
# `perSystem` module parameters
- `pkgs`: Defaults to `inputs.nixpkgs.legacyPackages.${system}`. Can be set via `config._module.args.pkgs`.
- `inputs'`: The flake `inputs` parameter, but with `system` pre-selected. Note the last character of the name, `'`, pronounced "prime".
`system` selection is handled by the extensible function [`perInput`](https://flake.parts/options.html#opt-perInput).
- `self'`: The flake `self` parameter, but with `system` pre-selected. This might trigger an infinite recursion (#22), so prefer `config`.
- `system`: The system parameter, describing the architecture and platform of
the host system (where the thing will run).
# Equivalences
- Getting the locally defined `hello` package on/for an `x86_64-linux` host:
- `nix build #hello` (assuming [`systems`](https://flake.parts/options.html#opt-systems) has `x86_64-linux`)
- `config.packages.hello` (if `config` is the `perSystem` module argument)
- `allSystems."x86_64-linux".packages.hello` (assuming [`systems`](https://flake.parts/options.html#opt-systems) has `x86_64-linux`)
- `(getSystem "x86_64-linux").packages.hello)`
- `withSystem "x86_64-linux" ({ config, ... }: config.packages.hello)`
Why so many ways?
1. Flakes counterintuitively handles `system` by enumerating all of them in attribute sets. `flake-parts` does not impose this restriction, but does need to support it.
2. `flake-parts` provides an extensible structure that is richer than the flakes interface alone.
# How do I define my own flake output attribute?
Have a look at the [source](https://github.com/hercules-ci/flake-parts/tree/main/modules) for some examples.
Whether directly or indirectly, you'll be defining an attribute inside [the `flake` option](https://flake.parts/options.html#opt-flake).
If you want the attribute to be derived from [`perSystem`](https://flake.parts/options.html#opt-perSystem) you can start with [`packages.nix`](https://github.com/hercules-ci/flake-parts/blob/main/modules/packages.nix) as an example, or [`formatter.nix`](https://github.com/hercules-ci/flake-parts/blob/main/modules/formatter.nix) if you need to do some filtering.
If you really don't care about your attribute, you may temporarily use [`transposition.<name>.adHoc = true`](https://flake.parts/options.html#opt-transposition._name_.adHoc) to create and expose a `perSystem` option without merging support, type checking or documentation.