docs: expand readme

1 files changed, 104 insertions, 85 deletions

diff --git a/README.md b/README.md
index cf41db6..9947674 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ yourself by following the instructions [here](https://garnix.io/docs/caching). i
 <summary>example</summary>
 
 ```nix
-{
+{pkgs, ...}: {
   nix.settings = {
     trusted-substituters = ["https://cache.garnix.io"];
 
@@ -25,13 +25,15 @@ yourself by following the instructions [here](https://garnix.io/docs/caching). i
 
 </details>
 
-### installing packages (flake)
+### flake-based
 
-you can add this repository as an input, and optionally override the nixpkgs input to build against
-your own revision. from there, you can use packages as an overlay or install them directly
+flakes are the primary supported method to use this repository - and in my opinion, can offer a much
+nicer user experience :)
 
-<details>
-<summary>with the overlay</summary>
+#### installing packages
+
+you can add this repository as an input, and optionally override the nixpkgs input to build against
+your own revision of nixpkgs
 
 ```nix
 {
@@ -44,7 +46,7 @@ your own revision. from there, you can use packages as an overlay or install the
     getchoo = {
       url = "github:getchoo/nix-exprs";
       # this will break reproducibility, but lower the instances of nixpkgs
-      # in flake.lock
+      # in flake.lock and possibly duplicated dependencies
       # inputs.nixpkgs.follows = "nixpkgs";
     };
   };
@@ -53,27 +55,29 @@ your own revision. from there, you can use packages as an overlay or install the
     nixpkgs,
     getchoo,
     ...
-  }: let
-    getchooModule = {
-      nixpkgs.overlays = [getchoo.overlays.default];
-      environment.systemPackages = [pkgs.treefetch];
-    };
-  in {
+  }: {
     nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
-      modules = [getchooModule];
-    };
-
-    darwinConfigurations.hostname = darwin.lib.darwinSystem {
-      modules = [getchooModule];
+      system = "x86_64-linux";
+      modules = [
+        ./configuration.nix
+
+        ({pkgs, ...}: {
+          environment.systemPackages = with getchoo.packages.${pkgs.system}; [
+            treefetch
+          ];
+        })
+      ];
     };
   };
 }
 ```
 
-</details>
-
 <details>
-<summary>directly</summary>
+<summary>using the overlay</summary>
+
+the overlay (though not preferred for the sake of reproducibility) is also an
+option for those who want to avoid the verbosity of installing packages directly,
+a "plug-n-play" solution to using the packages, and/or a reduction in duplicated dependencies.
 
 ```nix
 {
@@ -85,9 +89,9 @@ your own revision. from there, you can use packages as an overlay or install the
     };
     getchoo = {
       url = "github:getchoo/nix-exprs";
-      # this will break reproducibility, but lower the instances of nixpkgs
-      # in flake.lock
-      # inputs.nixpkgs.follows = "nixpkgs";
+      # this should probably be used in this scenario as reproducibility is
+      # already broken by using an overlay
+      inputs.nixpkgs.follows = "nixpkgs";
     };
   };
 
@@ -95,113 +99,128 @@ your own revision. from there, you can use packages as an overlay or install the
     nixpkgs,
     getchoo,
     ...
-  }: let
-    getchooModule = ({pkgs, ...}: let
-      inherit (pkgs.stdenv.hostPlatform) system;
-    in {
-      environment.systemPackages = [getchoo.packages.${system}.treefetch];
-    });
-  in {
+  }: {
     nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
-      modules = [getchooModule];
-    };
-
-    darwinConfigurations.hostname = darwin.lib.darwinSystem {
-      modules = [getchooModule];
+      system = "x86_64-linux";
+      modules = [
+        ./configuration.nix
+
+        ({pkgs, ...}: {
+          nixpkgs.overlays = [getchoo.overlays.default];
+          environment.systemPackages = with pkgs; [
+            treefetch
+          ];
+        })
+      ];
     };
   };
 }
 ```
 
+#### ad-hoc installation
+
+this flake can also be used in the base nix package manager!
+
+> **Note**
+> for nixos/nix-darwin users, `nixpkgs.overlays` does not configure
+> overlays for tools such as `nix(-)run`, `nix(-)shell`, etc. so this
+> will also be required for you
+
+the best way to make this overlay available for you is to
+add it to your flake registry like so.
+
+```sh
+nix registry add getchoo github:getchoo/nix-exprs
+nix profile install getchoo#treefetch
+nix shell getchoo#cfspeedtest
+```
+
 </details>
 
-### installing packages (without flakes)
+### standard nix
 
-this repository uses [flake-compat](https://github.com/edolstra/flake-compat) to allow for non-flake users to
-import a channel or the `default.nix` to access the flake's outputs.
+this repository uses [flake-compat](https://github.com/edolstra/flake-compat) to allow for non-flake environments to use the packages provided.
 
-<details>
-<summary>with the overlay</summary>
+there are two ways to do this: through channels or `fetchTarball` (or similar functions). i personally recommend
+channels as they are the easiest to update - though if you want to pin a specific revision of this repository,
+`fetchTarball` would probably be a better alternative.
+
+to add the channel, run:
+
+```sh
+nix-channel --add https://github.com/getchoo/nix-exprs/archive/main.tar.gz getchoo
+nix-channel --update getchoo
+
+```
+
+to use `fetchTarball`, please view the [documentation](https://nixos.org/manual/nix/stable/language/builtins.html?highlight=fetchtarball#builtins-fetchTarball) as there are a fair number of ways to use it.
+at it's most basic, you could use this:
+
+```nix
+{
+  getchoo = import (builtins.fetchTarball "https://github.com/getchoo/nix-exprs/archive/main.tar.gz");
+}
+```
+
+#### installing packages
 
 ```nix
 {pkgs, ...}: let
-  # install with `nix-channel --add https://github.com/getchoo/nix-exprs/archive/main.tar.gz getchoo`
+  # if you use channels
   getchoo = import <getchoo>;
 
-  # or use `fetchTarball`
+  # or if you use `fetchTarball`
   # getchoo = import (builtins.fetchTarball "https://github.com/getchoo/nix-exprs/archive/main.tar.gz");
 in {
-  nixpkgs.overlays = [getchoo.overlays.default];
-  environment.systemPackages = [pkgs.treefetch];
+  environment.systemPackages = [getchoo.packages.${pkgs.system}.treefetch];
 }
 ```
 
-</details>
-
 <details>
-<summary>directly</summary>
+<summary>with the overlay</summary>
 
 ```nix
 {pkgs, ...}: let
-  inherit (pkgs.stdenv.hostPlatform) system;
-
-  # install with `nix-channel --add https://github.com/getchoo/nix-exprs/archive/main.tar.gz getchoo`
+  # if you use channels
   getchoo = import <getchoo>;
 
-  # or use `fetchTarball`
+  # or if you use `fetchTarball`
   # getchoo = import (builtins.fetchTarball "https://github.com/getchoo/nix-exprs/archive/main.tar.gz");
 in {
-  environment.systemPackages = [getchoo.packages.${system}.treefetch];
+  nixpkgs.overlays = [getchoo.overlays.default];
+  environment.systemPackages = [pkgs.treefetch];
 }
 ```
 
 </details>
 
-### ad-hoc installation
-
-this flake can also be used in the base nix package manager :)
-
-> **Note**
-> for nixos/nix-darwin users, `nixpkgs.overlays` does not configure
-> overlays for tools such as `nix(-)run`, `nix(-)shell`, etc. so this
-> will also be required for you
-
-the best way to make this overlay available for you is to
-add it to your flake registry or `~/.config/nixpkgs/overlays.nix`.
-
-<details>
-<summary>flake registry</summary>
+#### ad-hoc installation
 
-this is the preferred way to use this overlay in the cli, as it allows
-for full reproducibility with the flake.
+there are two ways to use ad-hoc commands: through channels or `overlays.nix`.
 
-to use this overlay with commands like `nix build/run/shell/profile`, you can
-add it to your flake registry:
+channels are again then the preferred method here, where once it's added it can be used
+like so:
 
-```shell
-nix registry add getchoo github:getchoo/nix-exprs
-nix profile install getchoo#treefetch
+```sh
+nix-env -f '<getchoo>' -iA getchoo.packages.x86_64-linux.treefetch # replace x86_64-linux with your system
+nix-shell '<getchoo>' -p treefetch
 ```
 
-</details>
-
 <details>
 <summary>overlays.nix</summary>
 
-for those who don't want to use this flake's revision of nixpkgs,
-or do not use flakes, you can also add it as an overlay.
+for those who don't want to use this flake's revision of nixpkgs - or have the verbosity
+of the `flake-compat` provided commands - `overlays.nix` is a good option.
 
-first, add the channel for this repository with
-
-```sh
-nix-channel --add https://github.com/getchoo/nix-exprs/archive/main.tar.gz getchoo
-```
-
-then in `~/.config/nixpkgs/overlays.nix`:
+in `~/.config/nixpkgs/overlays.nix`:
 
 ```nix
 let
+  # if you use channels
   getchoo = import <getchoo>;
+
+  # or if you use `fetchTarball`
+  # getchoo = import (builtins.fetchTarball "https://github.com/getchoo/nix-exprs/archive/main.tar.gz");
 in [getchoo.overlays.default]
 ```