From 39067fc705b636d97fed021f7168ff34f550a0e5 Mon Sep 17 00:00:00 2001 From: Jade Lovelace Date: Wed, 10 Jul 2024 22:43:09 +0200 Subject: [PATCH] Automate replacing the versions in the installation instructions This was so so bad. Let's at least make it less fiddly. --- content/add-to-config.md | 8 ++ content/add-to-config.md.in | 246 ++++++++++++++++++++++++++++++++++++ content/install.md | 10 +- content/install.md.in | 105 +++++++++++++++ update_version.py | 52 ++++++++ 5 files changed, 420 insertions(+), 1 deletion(-) create mode 100644 content/add-to-config.md.in create mode 100644 content/install.md.in create mode 100644 update_version.py diff --git a/content/add-to-config.md b/content/add-to-config.md index 0cf3c9cf..a768826f 100644 --- a/content/add-to-config.md +++ b/content/add-to-config.md @@ -5,6 +5,14 @@ date: "2024-04-27" author: "Lix Team" --- + + 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. diff --git a/content/add-to-config.md.in b/content/add-to-config.md.in new file mode 100644 index 00000000..b7034c50 --- /dev/null +++ b/content/add-to-config.md.in @@ -0,0 +1,246 @@ +--- +title: "Switching To Lix" +description: "or: how to make your existing configuration Delicious" +date: "2024-04-27" +author: "Lix Team" +--- + + + +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: + - 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. + +# Using Lix from nixpkgs + +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 +nix-eval-jobs. Consequently, those tools will be using whichever version of +CppNix is default in nixpkgs, likely leading to an inconsistent experience. It +is, however, easy, and it does not take the few minutes to compile Lix from +source. + +Add the following code to your NixOS configuration: + +```nix +{ pkgs, ... }: +{ + nix.package = pkgs.lix; +} +``` + +That's it, you're done. + +You can verify that it works by running the following command: + +```sh +$ nix --version +nix (Lix, like Nix) @VERSION@ +``` + +# 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/@VERSION@.tar.gz"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + + } + + # +} +``` + +Next, add the `lix-module` as one of the arguments to your output function: + +```nix +{ + # + + # Add the `lix-module` argument to your output function, as below: + outputs = {nixpkgs, lix-module, ...}: { + # + } +} +``` + +Add the Lix _NixOS Module_ to your configuration: + +```nix +{ + # + + # 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 = [ + + # This is the important part -- add this line to your module list! + lix-module.nixosModules.default + ]; + + }; + } + + # +} +``` + + + +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: + +```sh +$ nix --version +nix (Lix, like Nix) @VERSION@ +``` + +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/@VERSION@.tar.gz + # + # Note that the tag (e.g. @VERSION@) 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/@VERSION@.tar.gz"; + sha256 = "@NIXOS_MODULE_HASH@"; + }; + lixSrc = fetchTarball { + name = "source"; + url = "https://git.lix.systems/lix-project/lix/archive/@VERSION@.tar.gz"; + sha256 = "@LIX_ARCHIVE_HASH@"; + }; + # 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; } + ) + ]; + + # +} +``` + + + +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: + +```sh +$ nix --version +nix (Lix, like Nix) @VERSION@ +``` + +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). + +## Having Trouble? + +**One quick thing to check:** have you set `nix.package` anywhere in your configuration? +If so, your configuration option will override the Lix module. You'll want to remove it, first -- +or, if you're feeling savvy, point it to the provided Lix package. + +**Otherwise:** If you're having difficulty installing Lix, don't panic! Hop on over to our +[community page](/community), and check out the various ways to find help. diff --git a/content/install.md b/content/install.md index f556c916..0496f893 100644 --- a/content/install.md +++ b/content/install.md @@ -5,6 +5,14 @@ date: "2024-04-27" author: "Lix Team" --- + + Whether you're a new or returning user, **we're thrilled you've decided to pick up Lix!** Lix works out-of-the-box on most Linux and MacOS systems, including with system management tools @@ -70,7 +78,7 @@ Thanks to Nix, we can actually ask Lix to upgrade your system directly. Run the sudo --preserve-env=PATH nix run \ --experimental-features "nix-command flakes" \ --extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o=" \ - 'git+https://git@git.lix.systems/lix-project/lix?ref=refs/tags/2.90.0-rc1' -- \ + 'git+https://git.lix.systems/lix-project/lix?ref=refs/tags/2.90.0' -- \ upgrade-nix \ --extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o=" ``` diff --git a/content/install.md.in b/content/install.md.in new file mode 100644 index 00000000..73af2ba6 --- /dev/null +++ b/content/install.md.in @@ -0,0 +1,105 @@ +--- +title: "Installing Lix" +description: "or: how to make your configuration Delicious" +date: "2024-04-27" +author: "Lix Team" +--- + + + +Whether you're a new or returning user, **we're thrilled you've decided to pick up Lix!** + +Lix works out-of-the-box on most Linux and MacOS systems, including with system management tools +such as [home-manager](https://github.com/nix-community/home-manager) and +[nix-darwin](https://github.com/LnL7/nix-darwin) -- but, like any Nix-based system, some Nix background +knowledge is recommended before installation. + +If you're new to the Nix ecosystem, you may want to check out some [community resources](/resources) +first, to get familiar with how Nix works. + + +## On NixOS + +If you haven't already installed NixOS, do so using any upstream +[install image](https://nixos.org/download/#NixOS) and the instructions in the +[NixOS Manual](https://nixos.org/manual/nixos/stable/#sec-installation). + +Then, follow the [instructions to add Lix to your +configuration](/add-to-config). Both flake-based and non-flake-based +configurations are fully supported. + + +## On an Existing `nix-darwin` Install + +If you already have a [nix-darwin](https://github.com/LnL7/nix-darwin) installation, you +can use the same instructions as installing on a NixOS-based system. Follow the instructions +for either: + +- [flake-based configurations](/add-to-config#flake-based-configurations); or +- [non-flake configurations](/add-to-config#non-flake-configurations) + +depending on how you prefer to configure your system. + + +## On Any Other Linux/MacOS System + +You can either perform a **new install**, or choose to +**upgrade an existing install** to Lix. + +### New Installs + +The easiest way to install Lix is to use the [Lix Installer](https://git.lix.systems/lix-project/lix-installer)[^1]. +Open a terminal, and run the following command: + +```sh +curl -sSf -L https://install.lix.systems/lix | sh -s -- install +``` + +The installer will guide you through installing Lix -- and once it's finished, +you'll have a full, working installation. If you're not sure what to do, now is a +great time to check out some of the [community's resources on Nix](/resources). + +[^1]: a customized variant of the [Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer). + +### Existing Installs + +If you have an existing Nix installation, you should be able to upgrade by using a variant +of the `upgrade-nix` command. + +Thanks to Nix, we can actually ask Lix to upgrade your system directly. Run the following command: + +```sh +sudo --preserve-env=PATH nix run \ + --experimental-features "nix-command flakes" \ + --extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o=" \ + 'git+https://git.lix.systems/lix-project/lix?ref=refs/tags/@VERSION@' -- \ + upgrade-nix \ + --extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o=" +``` + +You should now have upgraded to Lix! You can verify this by asking the `nix` command +to report its version: + +```sh +$ nix --version +nix (Lix, like Nix) @VERSION@ +``` + +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). + +## Having Trouble? + +If you're having difficulty installing Lix, don't panic! Hop on over to our +[community page](/community), and check out the various ways to find help. + +## Feedback? + +If you have thoughts on these instructions, feel free to drop by our [community](/community), +or to [make a pull request to our website](https://git.lix.systems/lix-project/lix-website/pulls)! diff --git a/update_version.py b/update_version.py new file mode 100644 index 00000000..f264d8ec --- /dev/null +++ b/update_version.py @@ -0,0 +1,52 @@ +import subprocess +from pathlib import Path +import json + + +def get_archive_hash(url): + output = subprocess.check_output(['nix', 'store', 'prefetch-file', '--name', 'source', '--json', '--unpack', url]) + + data = json.loads(output) + return data['hash'] + + +def substitute_all(content: str, substitutions: dict[str, str]) -> str: + for sub, value in substitutions.items(): + content = content.replace(sub, value) + return content + + +def substitute_file(path: Path, substitutions: dict[str, str]): + content = path.with_name(path.name + '.in').read_text() + subbed = substitute_all(content, substitutions) + path.write_text(subbed) + + +def go(version: str): + BASE_URL = 'https://git.lix.systems' + files = [ + Path('./content/add-to-config.md'), + Path('./content/install.md') + ] + + substitutions = { + '@VERSION@': version, + '@LIX_ARCHIVE_HASH@': get_archive_hash(BASE_URL + f'/lix-project/lix/archive/{version}.tar.gz'), + '@NIXOS_MODULE_HASH@': get_archive_hash(BASE_URL + f'/lix-project/nixos-module/archive/{version}.tar.gz'), + } + + for file in files: + substitute_file(file, substitutions) + + +def main(): + import argparse + ap = argparse.ArgumentParser(description='Update versions of Lix in the website') + + ap.add_argument('version', help='Version to make the files at') + args = ap.parse_args() + + go(args.version) + +if __name__ == '__main__': + main()