-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Automate replacing the versions in the installation instructions
This was so so bad. Let's at least make it less fiddly.
- Loading branch information
Showing
5 changed files
with
420 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/@[email protected]"; | ||
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/@[email protected] | ||
# | ||
# 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/@[email protected]"; | ||
sha256 = "@NIXOS_MODULE_HASH@"; | ||
}; | ||
lixSrc = fetchTarball { | ||
name = "source"; | ||
url = "https://git.lix.systems/lix-project/lix/archive/@[email protected]"; | ||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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)! |
Oops, something went wrong.