forked from lix-project/lix-website
Automate replacing the versions in the installation instructions
This was so so bad. Let's at least make it less fiddly.
This commit is contained in:
parent
7e44247748
commit
39067fc705
|
|
@ -5,6 +5,14 @@ date: "2024-04-27"
|
||||||
author: "Lix Team"
|
author: "Lix Team"
|
||||||
---
|
---
|
||||||
|
|
||||||
|
<!--
|
||||||
|
HI!!!
|
||||||
|
The file add-to-config.md is generated by update_version.py by
|
||||||
|
substituting values into add-to-config.md.in.
|
||||||
|
|
||||||
|
Please don't edit add-to-config.md directly!
|
||||||
|
-->
|
||||||
|
|
||||||
If you have an existing configuration on **NixOS** or **nix-darwin**, there are
|
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.
|
a couple of ways to switch to Lix, all of which are relatively easy.
|
||||||
|
|
||||||
|
|
|
||||||
246
content/add-to-config.md.in
Normal file
246
content/add-to-config.md.in
Normal file
|
|
@ -0,0 +1,246 @@
|
||||||
|
---
|
||||||
|
title: "Switching To Lix"
|
||||||
|
description: "or: how to make your existing configuration Delicious"
|
||||||
|
date: "2024-04-27"
|
||||||
|
author: "Lix Team"
|
||||||
|
---
|
||||||
|
|
||||||
|
<!--
|
||||||
|
HI!!!
|
||||||
|
The file add-to-config.md is generated by update_version.py by
|
||||||
|
substituting values into add-to-config.md.in.
|
||||||
|
|
||||||
|
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:
|
||||||
|
- 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";
|
||||||
|
};
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
# <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 = [
|
||||||
|
|
||||||
|
# This is the important part -- add this line to your module list!
|
||||||
|
lix-module.nixosModules.default
|
||||||
|
];
|
||||||
|
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
# <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`):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
nix.settings.substituters = [
|
||||||
|
"https://cache.lix.systems"
|
||||||
|
];
|
||||||
|
|
||||||
|
nix.settings.trusted-public-keys = [
|
||||||
|
"cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o="
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
-->
|
||||||
|
|
||||||
|
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; }
|
||||||
|
)
|
||||||
|
];
|
||||||
|
|
||||||
|
# <configuration below omitted>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
<!--
|
||||||
|
FIXME: as above, doesn't work, we should not recommend it.
|
||||||
|
|
||||||
|
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`):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
nix.settings.substituters = [
|
||||||
|
"https://cache.lix.systems"
|
||||||
|
];
|
||||||
|
|
||||||
|
nix.settings.trusted-public-keys = [
|
||||||
|
"cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o="
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
-->
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
@ -5,6 +5,14 @@ date: "2024-04-27"
|
||||||
author: "Lix Team"
|
author: "Lix Team"
|
||||||
---
|
---
|
||||||
|
|
||||||
|
<!--
|
||||||
|
HI!!!
|
||||||
|
The file install.md is generated by update_version.py by
|
||||||
|
substituting values into install.md.in.
|
||||||
|
|
||||||
|
Please don't edit install.md directly!
|
||||||
|
-->
|
||||||
|
|
||||||
Whether you're a new or returning user, **we're thrilled you've decided to pick up Lix!**
|
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
|
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 \
|
sudo --preserve-env=PATH nix run \
|
||||||
--experimental-features "nix-command flakes" \
|
--experimental-features "nix-command flakes" \
|
||||||
--extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o=" \
|
--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 \
|
upgrade-nix \
|
||||||
--extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o="
|
--extra-substituters https://cache.lix.systems --extra-trusted-public-keys "cache.lix.systems:aBnZUw8zA7H35Cz2RyKFVs3H4PlGTLawyY5KRbvJR8o="
|
||||||
```
|
```
|
||||||
|
|
|
||||||
105
content/install.md.in
Normal file
105
content/install.md.in
Normal file
|
|
@ -0,0 +1,105 @@
|
||||||
|
---
|
||||||
|
title: "Installing Lix"
|
||||||
|
description: "or: how to make your configuration Delicious"
|
||||||
|
date: "2024-04-27"
|
||||||
|
author: "Lix Team"
|
||||||
|
---
|
||||||
|
|
||||||
|
<!--
|
||||||
|
HI!!!
|
||||||
|
The file install.md is generated by update_version.py by
|
||||||
|
substituting values into install.md.in.
|
||||||
|
|
||||||
|
Please don't edit install.md directly!
|
||||||
|
-->
|
||||||
|
|
||||||
|
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)!
|
||||||
52
update_version.py
Normal file
52
update_version.py
Normal file
|
|
@ -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()
|
||||||
Loading…
Reference in a new issue