🦀🦀🦀🦀🦀🦀🦀 pull request 'content/add-to-config: recommend nixpkgs for stable versions' (#58) from new-mechanism into main

Reviewed-on: https://git.lix.systems/lix-project/lix-website/pulls/58

Author: jade

content/add-to-config.md

@@ -16,18 +16,26 @@ Please don't edit add-to-config.md directly!
 If you have an existing configuration on **NixOS** or **nix-darwin**, there are
 a couple of ways to switch to Lix, all of which are relatively easy.
 
-- Using Lix from nixpkgs:
-  - Potentially slightly older version of Lix
-  - Working binary caching
-  - Programs like nix-eval-jobs and colmena still use the default version of
-    Nix (may be unacceptable depending on your use case)
-- Using the Lix NixOS module:
+- Using Lix from nixpkgs (recommended for stable, released versions):
+  - Official, supported builds maintained by the `nixpkgs` contributors and the Lix team
+  - Is cached by `cache.nixos.org`, no local builds are required
+  - Consistent compatibility with advanced features of Nixpkgs: cross compilation or static builds.
+- Using the Lix NixOS module, [only recommended if you run main](https://wiki.lix.systems/books/lix-contributors/page/running-lix-main)
   - Fresh version of Lix right out of the freezer
   - You will be compiling Lix yourself, for now at least
-  - Programs like nix-eval-jobs and colmena have the version of Nix they use
-    overridden by an overlay such that most of the system uses Lix.
+  - Build stability may vary, as `nixpkgs` updates can occasionally introduce breaking changes
 
-# Using Lix from nixpkgs
+Running bleeding-edge (i.e. the `main` branch) Lix should not prevent you from using your system, we
+take this seriously and strive to ensure it works reliably. 
+
+That said, issues can happen. If you choose to run bleeding-edge, make sure you
+have a way to recover your system in case Lix breaks. 
+
+# Using Lix from nixpkgs (recommended)
+
+Using Lix from nixpkgs is the most recommended way if you are not using bleeding edge HEAD builds.
+
+## Simplest change
 
 This approach has some caveats: since it is not using an overlay, it does not
 set the version of Nix depended on by other tools like colmena or
@@ -41,7 +49,7 @@ Add the following code to your NixOS configuration:
 ```nix
 { pkgs, ... }:
 {
-  nix.package = pkgs.lix;
+  nix.package = pkgs.lixPackageSets.stable.lix;
 }
 ```
 
@@ -54,187 +62,68 @@ $ nix --version
 nix (Lix, like Nix) 2.93.3
 ```
 
-# Using the Lix NixOS module
-
-The Lix NixOS module is the way to get the most consistent experience using
-Lix, and to have a system that has Lix as the default Nix implementation
-wherever possible by using an overlay to replace `pkgs.nix`. It will result in
-building Lix from source, which takes a few minutes on every update, which is a
-perfect time to get up, get some water, and stretch for a bit.
-
-## Flake-based Configurations
-
-Adding Lix to a flake-based configuration is relatively simple. First, add the Lix module to your _flake inputs_:
-
-```nix
-{
-  inputs = {
-
-    # Add this section to your flake inputs!
-    #
-    # Note that this assumes you have a flake-input called nixpkgs,
-    # which is often the case. If you've named it something else,
-    # you'll need to change the `nixpkgs` below.
-    lix-module = {
-      url = "https://git.lix.systems/lix-project/nixos-module/archive/2.93.3-1.tar.gz";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
-
-  }
-
-  # <rest of configuration omitted>
-}
-```
-
-Next, add the `lix-module` as one of the arguments to your output function:
-
-```nix
-{
-  # <configuration above omitted>
-
-  # Add the `lix-module` argument to your output function, as below:
-  outputs = {nixpkgs, lix-module, ...}: {
-      # <rest of configuration omitted>
-  }
-}
-```
-
-Add the Lix _NixOS Module_ to your configuration:
-
-```nix
-{
-  # <configuration above omitted>
-
-  # Add the `lix-module` argument to your output function, as below:
-  outputs = {nixpkgs, lix-module, ...}: {
-
-      # The configuration here is an example; it will look slightly different
-      # based on your platform (NixOS, nix-darwin) and architecture.
-      nixosConfigurations.your-box = nixpkgs.lib.nixosSystem {
-        system = "x86_64-linux"
-
-        modules = [
+## Advanced change
 
-          # This is the important part -- add this line to your module list!
-          lix-module.nixosModules.default
-        ];
+This approach is more robust, as it uses an overlay to rewire other tools that depend on Nix, ensuring consistency across your setup. Tools like `colmena` or `nix-eval-jobs`, which often hardcode a reference to Nix, will now use the version provided by Lix.
 
-      };
-  }
-
-  # <configuration below omitted>
-}
-```
-
-<!--
-FIXME: the binary cache doesn't do much good given that everyone is running a
-different nixpkgs than Lix is actually cached with during the release process.
-We need a hydra to be able to fix that.
-
-Finally, if you'd prefer not to build Lix yourself, you can add our binary cache.
-Add the following to any NixOS module in your configuration (e.g. `configuration.nix`):
+Add the following code to your NixOS configuration:
 
 ```nix
+{ pkgs, ... }:
 {
-  nix.settings.substituters = [
-    "https://cache.lix.systems"
-  ];
-
-  nix.settings.trusted-public-keys = [
-    "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o="
-  ];
+  nixpkgs.overlays = [ (final: prev: {
+    inherit (final.lixPackageSets.stable)
+      nixpkgs-review
+      nix-direnv
+      nix-eval-jobs
+      nix-fast-build
+      colmena;
+  }) ];
+
+  nix.package = pkgs.lixPackageSets.stable.lix;
 }
 ```
 
--->
+That's it, your environment is now consistently using Lix across supported tools.
 
-Rebuild and switch into your new system (either using `nixos-rebuild` or `darwin-rebuild`).
-You should now be using Lix! You can verify this by asking the `nix` command to report its version:
+You can verify that it works by running the following command:
 
 ```sh
 $ nix --version
 nix (Lix, like Nix) 2.93.3
 ```
 
-As long as you see `Lix` in the output, you're good! If you're not sure what to do now, it's a
-great time to check out some of the [community's resources on Nix](/resources).
-
-
-## Non-Flake Configurations
-
-If you're not using flakes, you can set up your configuration to automatically pull down a
-Lix release tarball, and then add it to your `configuration.nix`.
-
-Open your `/etc/nixos/configuration.nix` in the editor of your choice. Find the `imports`
-section, and add the line provided in the configuration
-
-```nix
-{ config, lib, pkgs, ... }:
-{
-  imports =
-    [ # Include the results of the hardware scan.
-      ./hardware-configuration.nix
-
-      # This includes the Lix NixOS module in your configuration along with the
-      # matching version of Lix itself.
-      #
-      # The sha256 hashes were obtained with the following command in Lix (n.b.
-      # this relies on --unpack, which is only in Lix and CppNix > 2.18):
-      # nix store prefetch-file --name source --unpack https://git.lix.systems/lix-project/lix/archive/2.93.3.tar.gz
-      #
-      # Note that the tag (e.g. 2.93.3) in the URL here is what determines
-      # which version of Lix you'll wind up with.
-      (let
-        module = fetchTarball {
-          name = "source";
-          url = "https://git.lix.systems/lix-project/nixos-module/archive/2.93.3-1.tar.gz";
-          sha256 = "sha256-KYMUrTV7H/RR5/HRnjV5R3rRIuBXMemyJzTLi50NFTs=";
-        };
-        lixSrc = fetchTarball {
-          name = "source";
-          url = "https://git.lix.systems/lix-project/lix/archive/2.93.3.tar.gz";
-          sha256 = "sha256-Oqw04eboDM8rrUgAXiT7w5F2uGrQdt8sGX+Mk6mVXZQ=";
-        };
-        # This is the core of the code you need; it is an exercise to the
-        # reader to write the sources in a nicer way, or by using npins or
-        # similar pinning tools.
-        in import "${module}/module.nix" { lix = lixSrc; }
-      )
-    ];
-
-  # <configuration below omitted>
-}
-```
+---
 
-<!--
-FIXME: as above, doesn't work, we should not recommend it.
+To use a different version of Lix, replace `stable` with `latest`, `git`, or a specific version like `lix_2_93`.
 
-Finally, if you'd prefer not to build Lix yourself, you can add our binary cache.
-Add the following to any NixOS module in your configuration (e.g. `configuration.nix`):
+You can also rewire other packages manually. For example, to override a package so that it uses the Lix version of Nix:
 
 ```nix
+{ pkgs, ... }:
 {
-  nix.settings.substituters = [
-    "https://cache.lix.systems"
-  ];
-
-  nix.settings.trusted-public-keys = [
-    "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o="
-  ];
+  nixpkgs.overlays = [ (final: prev: {
+    my-new-package = prev.my-new-package.override {
+      nix = final.lixPackageSets.stable.lix;
+    }; # Adapt to your specific use case.
+
+    inherit (final.lixPackageSets.stable)
+      nixpkgs-review
+      nix-direnv
+      nix-eval-jobs
+      nix-fast-build
+      colmena;
+  }) ];
+
+  nix.package = pkgs.lixPackageSets.stable.lix;
 }
 ```
--->
 
-Rebuild and switch into your new system (either using `nixos-rebuild` or `darwin-rebuild`).
-You should now be using Lix! You can verify this by asking the `nix` command to report its version:
+# Using the Lix NixOS module (only recommended for bleeding edge builds)
 
-```sh
-$ nix --version
-nix (Lix, like Nix) 2.93.3
-```
+_Thank you for considering Lix bleeding edge, this helps us a lot to make Lix better._
 
-As long as you see `Lix` in the output, you're good! If you're not sure what to do now, it's a
-great time to check out some of the [community's resources on Nix](/resources).
+The instructions are maintained on <https://wiki.lix.systems/books/lix-contributors/page/running-lix-main>.
 
 ## Having Trouble?