From ee728efb75096431bb94f746d990f2dc786b0be2 Mon Sep 17 00:00:00 2001
From: seth <getchoo@tuta.io>
Date: Mon, 25 Dec 2023 04:35:25 -0500
Subject: treewide!: support variable root outputs (#6)

---
 README.md | 107 ++++++++++++++++++++++++++++++++++----------------------------
 1 file changed, 58 insertions(+), 49 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 656adaa..83dd3ae 100644
--- a/README.md
+++ b/README.md
@@ -1,91 +1,100 @@
 # nix2workflow
 
-![test status](https://github.com/getchoo/nix2workflow/actions/workflows/ci.yaml/badge.svg)
+![Test Status](https://github.com/getchoo/nix2workflow/actions/workflows/ci.yaml/badge.svg)
 [![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/getchoo/nix2workflow/badge)](https://flakehub.com/flake/getchoo/nix2workflow)
 
-nix2workflow is a library for generating github matrices from regular nix flake outputs.
+nix2workflow is a library for generating GitHub matrices from nix flake outputs.
 
-## usage
+## Usage
 
-we offer both a standard library for use in any flake, along with
+We offer both a standard library for use in any flake, along with
 a [flake-parts](https://flake.parts/) module for easier integration.
 
-you can find an example workflow for use in your own project in
+You can find an example workflow for use in your own project in
 [./.github/workflows/example.yaml](./.github/workflows/example.yaml).
 
-### flake module
+### Flake module
 
-a basic setup might look like this. please see the [module](./module.nix)
+A basic setup might look like this. Please see the [module](./module.nix)
 for all options
 
 ```nix
-{
-  imports = [nix2workflow.flakeModule];
+{self, ...}: {
+  imports = [ nix2workflow.flakeModule ];
 
-  githubWorkflowGenerator = {
-    outputs = [
-      "checks"
-      "devShells"
-      "nixosConfigurations"
-      "packages"
-    ];
+  nix2workflow = {
+    # this will automatically build all standard outputs in self
+    root = self;
 
     overrides = {
-      checks.systems = ["x86_64-linux"];
+      checks.systems = [ "x86_64-linux" ];
     };
   };
 }
 ```
 
-a full example can be found in [./test/module/flake.nix](./test/module/flake.nix)
+A full example can be found in [./test/module/flake.nix](./test/module/flake.nix)
 
-### library
+### Library
 
-the regular library will have a more complicated setup, though
+The regular library will have a more complicated setup, though
 it also allows using lower level functions and has no restrictions on
 what flake outputs are used.
 
 ```nix
 {
-  githubworkflow = let
-    workflow = nix2workflow.lib {inherit self;};
-    outputs = [
-      "checks"
-      "devShells"
-      "nixosConfigurations"
-      "packages"
-    ];
-  in {
-    matrix.include = lib.concatLists (
-      map (
-        output:
-          workflow.mkMatrix {
-            inherit output;
-            # you can also specify what systems to build each output for
-            systems = ["x86_64-linux" "aarch64-darwin"];
-          }
-      )
-      outputs
+  workflowMatrix = let
+    platforms = {
+      x86_64-linux = {
+        os = "ubuntu-latest";
+        arch = "x64";
+      };
+
+      x86_64-darwin = {
+        os = "macos-latest";
+        arch = "x64";
+      };
+    };
+
+    inherit (nix2workflow.lib { inherit platforms; }) mkMatrix;
+
+    jobs = lib.flatten (
+      (mkMatrix {
+        root = self;
+        output = "packages";
+      })
+
+      (mkMatrix {
+        root = self;
+        output = "checks";
+        systems = [ "x86_64-linux" ];
+      })
     );
+  in {
+    include = jobs;
   };
 }
 ```
 
-you can see a full example in [./test/lib/flake.nix](./test/lib/flake.nix)
+You can see a full example in [./test/lib/flake.nix](./test/lib/flake.nix)
 
-### in workflows
+### In workflows
 
-when the matrix is imported, a few variables with added to the `matrix` context.
-these can allow you to customize your workflow based on what packages are building -
+When the matrix is imported, a few variables with added to the `matrix` context.
+These can allow you to customize your workflow based on what packages are building -
 such as enabling QEMU when building for aarch64
 
 | name | use |
 | --- | --- |
-| `os` | the operating system of the current output. usually `ubuntu-latest` or `macos-latest` |
-| `arch` | the architecture of the current output. will be `aarch64` or `x64` |
-| `attr` | the flake attribute of the current output (can really be anything) |
+| `os` | The operating system of the current output. Usually `ubuntu-latest` or `macos-latest` |
+| `arch` | The architecture of the current output. Will be `aarch64` or `x64` |
+| `attr` | The flake attribute of the current output (can really be anything).
+ Note that you will still need to prefix this with the `root` attribute if set (i.e. `.#hydraJobs.${{ matrix.attrr }}`) |
 
-## related projects
+## Related projects
   - [nix-community/nix-github-actions](https://github.com/nix-community/nix-github-actions/)
-    - this is the primary inspiration for this project - and i believe also one of the first 
-    projects to attempt this, so kudos! i just wanted a more opionated and expandable approach :)
+    - This is the primary inspiration for this project - and I believe also one of the first 
+    projects to attempt this, so kudos!
+  - [nix-community/nix-eval-jobs](https://github.com/nix-community/nix-eval-jobs)
+    - I liked the idea of using `hydraJobs` (and possibly others) on GitHub Actions, and
+    thought it might be fun to make a direct translation of these attributes in pure nix
-- 
cgit v1.2.3