diff --git a/README.md b/README.md index 98c67f6..7d86a0a 100644 --- a/README.md +++ b/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) 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..a75b9d6 --- /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); 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 +``` diff --git a/examples/project-commands/flake.lock b/examples/project-commands/flake.lock new file mode 100644 index 0000000..6179e83 --- /dev/null +++ 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 new file mode 100644 index 0000000..0f72c1c --- /dev/null +++ b/examples/shell-environments/README.md @@ -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`. 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 +} diff --git a/examples/shell-environments/flake.nix b/examples/shell-environments/flake.nix new file mode 100644 index 0000000..25b4045 --- /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 nixpkgs-fmt ]; + }; + + devShells.another_env = pkgs.mkShell { + nativeBuildInputs = with pkgs; [ curl ]; + }; + }; + + }; +} diff --git a/modules/devShells.nix b/modules/devShells.nix index d14e59e..c0cc6c5 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 '' + { + default = pkgs.mkShell { + nativeBuildInputs = with pkgs; [ wget bat cargo ]; + }; + } + ''; }; file = ./devShells.nix; }