mirror of
https://github.com/hercules-ci/flake-parts.git
synced 2024-12-14 11:47:31 +00:00
Merge #171
171: Add more docs r=roberth a=woile This PR adds the following: - an examples folder - an example for devShell - templates are no longer marked as examples, now there are templates and examples avoiding confusion #170 Co-authored-by: Santiago Fraire <santiwilly@gmail.com> Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
This commit is contained in:
bors[bot]
GitHub
commit
8e8d955c22
9 changed files with 349 additions and 7 deletions
28
README.md
28
README.md
|
|
@ -3,12 +3,18 @@
|
|||
|
||||
_Core of a distributed framework for writing Nix Flakes._
|
||||
|
||||
`flake-parts` provides the options that represent standard flake attributes
|
||||
`flake-parts` provides the options that represent standard flake attributes
|
||||
and establishes a way of working with `system`.
|
||||
Opinionated features are provided by an ecosystem of modules that you can import.
|
||||
|
||||
`flake-parts` _itself_ has the goal to be a minimal mirror of the Nix flake schema.
|
||||
Used by itself, it is very lightweight.
|
||||
Used by itself, it is very lightweight.
|
||||
|
||||
---
|
||||
|
||||
**Documentation**: [flake.parts](https://flake.parts)
|
||||
|
||||
---
|
||||
|
||||
# Why Modules?
|
||||
|
||||
|
|
@ -71,14 +77,22 @@ then slide `mkFlake` between your outputs function head and body,
|
|||
|
||||
Now you can add the remaining module attributes like in the [the template](./template/default/flake.nix).
|
||||
|
||||
# Example
|
||||
# Templates
|
||||
|
||||
See [the template](./template/default/flake.nix).
|
||||
|
||||
# Examples
|
||||
|
||||
See the [examples/](./examples) directory.
|
||||
|
||||
# Projects using flake-parts
|
||||
|
||||
- [nixd](https://github.com/nix-community/nixd/blob/main/flake.nix) (c++)
|
||||
- [hyperswitch](https://github.com/juspay/hyperswitch/blob/main/flake.nix) (rust)
|
||||
- [argo-workflows](https://github.com/argoproj/argo-workflows/blob/master/dev/nix/flake.nix) (go)
|
||||
- [nlp-service](https://github.com/recap-utr/nlp-service/blob/main/flake.nix) (python)
|
||||
- [emanote](https://github.com/srid/emanote/blob/master/flake.nix) (haskell)
|
||||
|
||||
# Options Reference
|
||||
|
||||
See [flake.parts options](https://flake.parts/options/flake-parts.html)
|
||||
|
||||
# Documentation
|
||||
|
||||
See [flake.parts](https://flake.parts)
|
||||
|
|
|
|||
6
examples/project-commands/Hello.avdl
Normal file
6
examples/project-commands/Hello.avdl
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
protocol Hello {
|
||||
record Hello {
|
||||
string message;
|
||||
int timestamp;
|
||||
}
|
||||
}
|
||||
42
examples/project-commands/README.md
Normal file
42
examples/project-commands/README.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# project-commands
|
||||
|
||||
> **Warning**
|
||||
> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
|
||||
|
||||
This example shows how to create scripts for your project, by leveraging [mission-control](https://github.com/Platonic-Systems/mission-control)
|
||||
|
||||
This is a **potential** alternative to:
|
||||
|
||||
- Using a `Makefile` to manage your project's scripts
|
||||
- Using the popular [Scripts To Rule Them All](https://github.com/github/scripts-to-rule-them-all); a naming convention for a `scripts/` directory
|
||||
- Using a `bin/` directory
|
||||
|
||||
## Explanation
|
||||
|
||||
In this example we use the [avro-tools](https://avro.apache.org/) to convert our scripts from `.avdl` to `.avsc`.
|
||||
|
||||
You don't need to know anything about avro to understand mission-control and use this example (that's Nix baby 🚀).
|
||||
|
||||
When setting up [mission-control](https://github.com/Platonic-Systems/mission-control), we add
|
||||
one script called `build`. Because of `wrapperName = "run";`, once we open the shell created by nix,
|
||||
the commands will be listed as `run build`.
|
||||
|
||||
mission-control depends on flake-root, which also exposes the helpful `$FLAKE_ROOT` variable.
|
||||
|
||||
After creating the scripts, we need to pass the newly created scripts to the desired shell, in this example we use the default shell.
|
||||
|
||||
## Usage
|
||||
|
||||
Run:
|
||||
|
||||
```sh
|
||||
nix develop
|
||||
```
|
||||
|
||||
And mission-control will print in the new shell the available commands (you should see only one).
|
||||
|
||||
Try running
|
||||
|
||||
```sh
|
||||
run build
|
||||
```
|
||||
95
examples/project-commands/flake.lock
Normal file
95
examples/project-commands/flake.lock
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
{
|
||||
"nodes": {
|
||||
"flake-parts": {
|
||||
"inputs": {
|
||||
"nixpkgs-lib": "nixpkgs-lib"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1685662779,
|
||||
"narHash": "sha256-cKDDciXGpMEjP1n6HlzKinN0H+oLmNpgeCTzYnsA2po=",
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"rev": "71fb97f0d875fd4de4994dfb849f2c75e17eb6c3",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"id": "flake-parts",
|
||||
"type": "indirect"
|
||||
}
|
||||
},
|
||||
"flake-root": {
|
||||
"locked": {
|
||||
"lastModified": 1680964220,
|
||||
"narHash": "sha256-dIdTYcf+KW9a4pKHsEbddvLVSfR1yiAJynzg2x0nfWg=",
|
||||
"owner": "srid",
|
||||
"repo": "flake-root",
|
||||
"rev": "f1c0b93d05bdbea6c011136ba1a135c80c5b326c",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "flake-root",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"mission-control": {
|
||||
"locked": {
|
||||
"lastModified": 1683658484,
|
||||
"narHash": "sha256-JkGnWyYZxOnyOhztrxLSqaod6+O/3rRypq0dAqA/zn0=",
|
||||
"owner": "Platonic-Systems",
|
||||
"repo": "mission-control",
|
||||
"rev": "a0c93bd764a3c25e6999397e9f5f119c1b124e38",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "Platonic-Systems",
|
||||
"repo": "mission-control",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1687502512,
|
||||
"narHash": "sha256-dBL/01TayOSZYxtY4cMXuNCBk8UMLoqRZA+94xiFpJA=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "3ae20aa58a6c0d1ca95c9b11f59a2d12eebc511f",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs-lib": {
|
||||
"locked": {
|
||||
"dir": "lib",
|
||||
"lastModified": 1685564631,
|
||||
"narHash": "sha256-8ywr3AkblY4++3lIVxmrWZFzac7+f32ZEhH/A8pNscI=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "4f53efe34b3a8877ac923b9350c874e3dcd5dc0a",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"dir": "lib",
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"flake-parts": "flake-parts",
|
||||
"flake-root": "flake-root",
|
||||
"mission-control": "mission-control",
|
||||
"nixpkgs": "nixpkgs"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
||||
37
examples/project-commands/flake.nix
Normal file
37
examples/project-commands/flake.nix
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
{
|
||||
description = "Description for the project";
|
||||
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
|
||||
mission-control.url = "github:Platonic-Systems/mission-control";
|
||||
flake-root.url = "github:srid/flake-root";
|
||||
};
|
||||
|
||||
outputs = inputs@{ flake-parts, ... }:
|
||||
flake-parts.lib.mkFlake { inherit inputs; } {
|
||||
imports = [
|
||||
inputs.mission-control.flakeModule
|
||||
inputs.flake-root.flakeModule
|
||||
];
|
||||
systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
|
||||
perSystem = { config, self', inputs', pkgs, system, ... }: {
|
||||
devShells.default = pkgs.mkShell {
|
||||
nativeBuildInputs = with pkgs; [ avro-tools ];
|
||||
inputsFrom = [ config.mission-control.devShell config.flake-root.devShell ];
|
||||
};
|
||||
mission-control = {
|
||||
wrapperName = "run";
|
||||
scripts = {
|
||||
build = {
|
||||
description = "convert files from .avdl to .avsc";
|
||||
exec = ''
|
||||
avro-tools idl2schemata "$FLAKE_ROOT/Hello.avdl" .
|
||||
'';
|
||||
category = "Development";
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
55
examples/shell-environments/README.md
Normal file
55
examples/shell-environments/README.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
# shell-environment
|
||||
|
||||
> **Warning**
|
||||
> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
|
||||
|
||||
This example shows how to create a shell environment which
|
||||
includes a diverse set of tools:
|
||||
|
||||
```sh
|
||||
terraform
|
||||
wget
|
||||
bat
|
||||
nixpkgs-fmt
|
||||
```
|
||||
|
||||
You can search for more packages in [nix packages](https://search.nixos.org/packages)
|
||||
|
||||
## Usage
|
||||
|
||||
The [`devShells` option](https://flake.parts/options/flake-parts.html#opt-perSystem.devShells) is used by the following command:
|
||||
|
||||
```sh
|
||||
nix develop
|
||||
```
|
||||
|
||||
You can have as many shells as you want, in this [flake.nix](./flake.nix), you also have
|
||||
`another_env` which includes `curl`. To open it:
|
||||
|
||||
```sh
|
||||
nix develop .#another_env
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### I get bash instead of my shell
|
||||
|
||||
`nix develop` was designed for Nixpkgs stdenv, which uses bash, so that you can troubleshoot a Nix build with it. If you use a different shell, you'll want to get just the variables instead.
|
||||
|
||||
There are 3 possible solutions:
|
||||
|
||||
First, using [direnv](https://direnv.net/) to manage your dev environments. See [direnv-guide](https://haskell.flake.page/direnv). This is the recommended approach.
|
||||
|
||||
Second is a simple-unreliable hack, which is adding a `shellHook` to `devShells`
|
||||
|
||||
```nix
|
||||
devShells.default = pkgs.mkShell {
|
||||
shellHook = ''
|
||||
exec $SHELL
|
||||
'';
|
||||
};
|
||||
```
|
||||
|
||||
You might get a lot different issues, use it at your own risk.
|
||||
|
||||
Lastly, there's `nix print-dev-env` which returns the variables - in case you're feeling adventurous, because this is far from a complete solution. See `nix print-dev-env --help`.
|
||||
63
examples/shell-environments/flake.lock
Normal file
63
examples/shell-environments/flake.lock
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
{
|
||||
"nodes": {
|
||||
"flake-parts": {
|
||||
"inputs": {
|
||||
"nixpkgs-lib": "nixpkgs-lib"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1685662779,
|
||||
"narHash": "sha256-cKDDciXGpMEjP1n6HlzKinN0H+oLmNpgeCTzYnsA2po=",
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"rev": "71fb97f0d875fd4de4994dfb849f2c75e17eb6c3",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"id": "flake-parts",
|
||||
"type": "indirect"
|
||||
}
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1687412861,
|
||||
"narHash": "sha256-Z/g0wbL68C+mSGerYS2quv9FXQ1RRP082cAC0Bh4vcs=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "e603dc5f061ca1d8a19b3ede6a8cf9c9fcba6cdc",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs-lib": {
|
||||
"locked": {
|
||||
"dir": "lib",
|
||||
"lastModified": 1685564631,
|
||||
"narHash": "sha256-8ywr3AkblY4++3lIVxmrWZFzac7+f32ZEhH/A8pNscI=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "4f53efe34b3a8877ac923b9350c874e3dcd5dc0a",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"dir": "lib",
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"flake-parts": "flake-parts",
|
||||
"nixpkgs": "nixpkgs"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
||||
22
examples/shell-environments/flake.nix
Normal file
22
examples/shell-environments/flake.nix
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
{
|
||||
description = "Description for the project";
|
||||
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
};
|
||||
|
||||
outputs = inputs@{ flake-parts, ... }:
|
||||
flake-parts.lib.mkFlake { inherit inputs; } {
|
||||
systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
|
||||
perSystem = { config, self', inputs', pkgs, system, ... }: {
|
||||
devShells.default = pkgs.mkShell {
|
||||
nativeBuildInputs = with pkgs; [ terraform wget bat nixpkgs-fmt ];
|
||||
};
|
||||
|
||||
devShells.another_env = pkgs.mkShell {
|
||||
nativeBuildInputs = with pkgs; [ curl ];
|
||||
};
|
||||
};
|
||||
|
||||
};
|
||||
}
|
||||
|
|
@ -3,6 +3,7 @@ let
|
|||
inherit (lib)
|
||||
mkOption
|
||||
types
|
||||
literalExpression
|
||||
;
|
||||
inherit (flake-parts-lib)
|
||||
mkTransposedPerSystemModule
|
||||
|
|
@ -17,6 +18,13 @@ mkTransposedPerSystemModule {
|
|||
An attribute set of packages to be used as shells.
|
||||
[`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
|
||||
'';
|
||||
example = literalExpression ''
|
||||
{
|
||||
default = pkgs.mkShell {
|
||||
nativeBuildInputs = with pkgs; [ wget bat cargo ];
|
||||
};
|
||||
}
|
||||
'';
|
||||
};
|
||||
file = ./devShells.nix;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue