From 02b1bdb2fe921d5df93124943580af6af6d67c32 Mon Sep 17 00:00:00 2001 From: Santiago Fraire Date: Fri, 23 Jun 2023 19:31:43 +0200 Subject: [PATCH] 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