From 93292ab70aa11ffe2dcac783997b3d0dda7b8c25 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Thu, 15 Jun 2023 22:08:54 +0200 Subject: [PATCH 1/9] docs: add example for devShells --- modules/devShells.nix | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/modules/devShells.nix b/modules/devShells.nix index d14e59e..5d672d6 100644 --- a/modules/devShells.nix +++ b/modules/devShells.nix @@ -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 .#`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.`. ''; + example = literalExpression '' + { + devShells.default = pkgs.mkShell { + nativeBuildInputs = with pkgs; [ wget bat git cargo ]; + }; + } + ''; }; file = ./devShells.nix; } From a530cce7214492b40aff5270d90f8daac9511413 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Thu, 15 Jun 2023 22:13:02 +0200 Subject: [PATCH 2/9] docs: add examples folder --- examples/shell-environments/README.md | 28 +++++++++++++++++++++++++++ examples/shell-environments/flake.nix | 22 +++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 examples/shell-environments/README.md create mode 100644 examples/shell-environments/flake.nix diff --git a/examples/shell-environments/README.md b/examples/shell-environments/README.md new file mode 100644 index 0000000..a5d81e8 --- /dev/null +++ b/examples/shell-environments/README.md @@ -0,0 +1,28 @@ +# shell-environment + +This example shows how to create a shell environment which +includes a diverse set of tools: + +``` +terraform +wget +bat +git +``` + +You can search for more package 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 +``` \ No newline at end of file diff --git a/examples/shell-environments/flake.nix b/examples/shell-environments/flake.nix new file mode 100644 index 0000000..298579c --- /dev/null +++ b/examples/shell-environments/flake.nix @@ -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 git ]; + }; + + devShells.another_env = pkgs.mkShell { + nativeBuildInputs = with pkgs; [ curl ]; + }; + }; + + }; +} From fa681367b39ef399468a04bbc36a4a8068b934b5 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Thu, 15 Jun 2023 22:26:45 +0200 Subject: [PATCH 3/9] docs(README): add examples and projects --- README.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 98c67f6..e0fcebc 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,12 @@ _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. # Why Modules? @@ -71,10 +71,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 folder [examples/](./examples). + +# 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) From 2cf8f2e746838cd94fcc58f7013aa77e5dd27b68 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Fri, 23 Jun 2023 19:31:29 +0200 Subject: [PATCH 4/9] docs: add lock to shell-environments --- examples/project-commands/flake.lock | 0 examples/shell-environments/README.md | 3 ++ examples/shell-environments/flake.lock | 63 ++++++++++++++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 examples/project-commands/flake.lock create mode 100644 examples/shell-environments/flake.lock diff --git a/examples/project-commands/flake.lock b/examples/project-commands/flake.lock new file mode 100644 index 0000000..e69de29 diff --git a/examples/shell-environments/README.md b/examples/shell-environments/README.md index a5d81e8..de18ac7 100644 --- a/examples/shell-environments/README.md +++ b/examples/shell-environments/README.md @@ -14,6 +14,9 @@ You can search for more package in [nix packages](https://search.nixos.org/packa ## Usage +> **Warning** +> If you copy the flake.nix remember to add it to git, otherwise it won't work + The [`devShells` option](https://flake.parts/options/flake-parts.html#opt-perSystem.devShells) is used by the following command: ```sh diff --git a/examples/shell-environments/flake.lock b/examples/shell-environments/flake.lock new file mode 100644 index 0000000..f1371b0 --- /dev/null +++ b/examples/shell-environments/flake.lock @@ -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 +} From 02b1bdb2fe921d5df93124943580af6af6d67c32 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Fri, 23 Jun 2023 19:31:43 +0200 Subject: [PATCH 5/9] docs: add commands example --- examples/project-commands/Hello.avdl | 6 ++ examples/project-commands/README.md | 42 ++++++++++++ examples/project-commands/flake.lock | 95 +++++++++++++++++++++++++++ examples/project-commands/flake.nix | 37 +++++++++++ examples/shell-environments/README.md | 6 +- 5 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 examples/project-commands/Hello.avdl create mode 100644 examples/project-commands/README.md create mode 100644 examples/project-commands/flake.nix diff --git a/examples/project-commands/Hello.avdl b/examples/project-commands/Hello.avdl new file mode 100644 index 0000000..2b3507f --- /dev/null +++ b/examples/project-commands/Hello.avdl @@ -0,0 +1,6 @@ +protocol Hello { + record Hello { + string message; + int timestamp; + } +} \ No newline at end of file diff --git a/examples/project-commands/README.md b/examples/project-commands/README.md new file mode 100644 index 0000000..2f459f4 --- /dev/null +++ b/examples/project-commands/README.md @@ -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) approach (having a `scripts/` folder) +- Using a `bin/` folder + +## 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 +``` diff --git a/examples/project-commands/flake.lock b/examples/project-commands/flake.lock index e69de29..6179e83 100644 --- a/examples/project-commands/flake.lock +++ b/examples/project-commands/flake.lock @@ -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 +} diff --git a/examples/project-commands/flake.nix b/examples/project-commands/flake.nix new file mode 100644 index 0000000..a8e070d --- /dev/null +++ b/examples/project-commands/flake.nix @@ -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"; + }; + }; + }; + }; + }; +} diff --git a/examples/shell-environments/README.md b/examples/shell-environments/README.md index de18ac7..5921bab 100644 --- a/examples/shell-environments/README.md +++ b/examples/shell-environments/README.md @@ -1,5 +1,8 @@ # 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: @@ -14,9 +17,6 @@ You can search for more package in [nix packages](https://search.nixos.org/packa ## Usage -> **Warning** -> If you copy the flake.nix remember to add it to git, otherwise it won't work - The [`devShells` option](https://flake.parts/options/flake-parts.html#opt-perSystem.devShells) is used by the following command: ```sh From 8fd103c90b37ef913577c1696f1c2011b3bfa704 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Sat, 24 Jun 2023 08:22:56 +0200 Subject: [PATCH 6/9] docs: add troubleshooting to shell-environemnts --- examples/shell-environments/README.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/examples/shell-environments/README.md b/examples/shell-environments/README.md index 5921bab..271c908 100644 --- a/examples/shell-environments/README.md +++ b/examples/shell-environments/README.md @@ -6,7 +6,7 @@ This example shows how to create a shell environment which includes a diverse set of tools: -``` +```sh terraform wget bat @@ -28,4 +28,25 @@ You can have as many shells as you want, in this [flake.nix](./flake.nix), you a ```sh nix develop .#another_env -``` \ No newline at end of file +``` + +## Troubleshooting + +### My shell has changed + +There 2 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. + From 1a3b8642614f33d296c58d63456c57b7d0606ab2 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Sat, 24 Jun 2023 08:36:14 +0200 Subject: [PATCH 7/9] docs: make documentation visible right away --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e0fcebc..d90011f 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,12 @@ 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. +--- + +**Documentation**: [flake.parts](https://flake.parts) + +--- + # Why Modules? Flakes are configuration. The module system lets you refactor configuration @@ -90,7 +96,3 @@ See the folder [examples/](./examples). # Options Reference See [flake.parts options](https://flake.parts/options/flake-parts.html) - -# Documentation - -See [flake.parts](https://flake.parts) From 6f53e9012c981d7e1e5bcf5bc17690af3f0d9560 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Mon, 26 Jun 2023 09:14:11 +0200 Subject: [PATCH 8/9] docs: update to comments --- README.md | 2 +- examples/project-commands/README.md | 6 +++--- examples/shell-environments/README.md | 13 ++++++++----- examples/shell-environments/flake.nix | 2 +- modules/devShells.nix | 8 ++++---- 5 files changed, 17 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index d90011f..7d86a0a 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ See [the template](./template/default/flake.nix). # Examples -See the folder [examples/](./examples). +See the [examples/](./examples) directory. # Projects using flake-parts diff --git a/examples/project-commands/README.md b/examples/project-commands/README.md index 2f459f4..a75b9d6 100644 --- a/examples/project-commands/README.md +++ b/examples/project-commands/README.md @@ -8,14 +8,14 @@ This example shows how to create scripts for your project, by leveraging [missio 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) approach (having a `scripts/` folder) -- Using a `bin/` folder +- 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 🚀). +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, diff --git a/examples/shell-environments/README.md b/examples/shell-environments/README.md index 271c908..4423ed4 100644 --- a/examples/shell-environments/README.md +++ b/examples/shell-environments/README.md @@ -10,10 +10,10 @@ includes a diverse set of tools: terraform wget bat -git +nixpkgs-fmt ``` -You can search for more package in [nix packages](https://search.nixos.org/packages) +You can search for more packages in [nix packages](https://search.nixos.org/packages) ## Usage @@ -32,7 +32,9 @@ nix develop .#another_env ## Troubleshooting -### My shell has changed +### 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 2 possible solutions: @@ -42,11 +44,12 @@ Second is a simple-unreliable hack, which is adding a `shellHook` to `devShells` ```nix devShells.default = pkgs.mkShell { - shellHook = '' + 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`. diff --git a/examples/shell-environments/flake.nix b/examples/shell-environments/flake.nix index 298579c..25b4045 100644 --- a/examples/shell-environments/flake.nix +++ b/examples/shell-environments/flake.nix @@ -10,7 +10,7 @@ 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 git ]; + nativeBuildInputs = with pkgs; [ terraform wget bat nixpkgs-fmt ]; }; devShells.another_env = pkgs.mkShell { diff --git a/modules/devShells.nix b/modules/devShells.nix index 5d672d6..c0cc6c5 100644 --- a/modules/devShells.nix +++ b/modules/devShells.nix @@ -19,11 +19,11 @@ mkTransposedPerSystemModule { [`nix develop .#`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.`. ''; example = literalExpression '' - { - devShells.default = pkgs.mkShell { - nativeBuildInputs = with pkgs; [ wget bat git cargo ]; + { + default = pkgs.mkShell { + nativeBuildInputs = with pkgs; [ wget bat cargo ]; }; - } + } ''; }; file = ./devShells.nix; From 7910deccec23fb2f49b0f3703aa2fee58e7173cf Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Tue, 4 Jul 2023 12:19:47 +0200 Subject: [PATCH 9/9] examples/shell-environments/README: typo --- examples/shell-environments/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/shell-environments/README.md b/examples/shell-environments/README.md index 4423ed4..0f72c1c 100644 --- a/examples/shell-environments/README.md +++ b/examples/shell-environments/README.md @@ -36,7 +36,7 @@ nix develop .#another_env `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 2 possible solutions: +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.