mirror of
https://github.com/ryan4yin/nixos-and-flakes-book.git
synced 2024-11-29 03:24:19 +01:00
435 lines
22 KiB
Markdown
435 lines
22 KiB
Markdown
# Enabling NixOS with Flakes
|
|
|
|
## Enabling Flakes Support for NixOS {#enable-nix-flakes}
|
|
|
|
Compared to the default configuration method currently used in NixOS, Flakes offers better reproducibility. Its clear package structure definition inherently supports dependencies on other Git repositories, facilitating code sharing. Therefore, this book suggests using Flakes to manage system configurations. Currently, Flakes is still an experimental feature and not enabled by default. We need to manually modify the `/etc/nixos/configuration.nix` file to enable the Flakes feature and the accompanying new nix command-line tool:
|
|
|
|
```nix{12,16}
|
|
{ config, pkgs, ... }:
|
|
|
|
{
|
|
imports = [
|
|
# Include the results of the hardware scan.
|
|
./hardware-configuration.nix
|
|
];
|
|
|
|
# ......
|
|
|
|
# Enable the Flakes feature and the accompanying new nix command-line tool
|
|
nix.settings.experimental-features = [ "nix-command" "flakes" ];
|
|
environment.systemPackages = with pkgs; [
|
|
# Flakes clones its dependencies through the git command,
|
|
# so git must be installed first
|
|
git
|
|
vim
|
|
wget
|
|
curl
|
|
];
|
|
# Set the default editor to vim
|
|
environment.variables.EDITOR = "vim";
|
|
|
|
# ......
|
|
}
|
|
```
|
|
|
|
After making these changes, run `sudo nixos-rebuild switch` to apply the modifications. Then, you can use the Flakes feature to manage your system configuration.
|
|
|
|
The new nix command-line tool also offers some convenient features. For example, you can now use the `nix repl` command to open a nix interactive environment.
|
|
If you're interested, you can use it to review and test all the Nix syntax you've learned before.
|
|
|
|
|
|
## Switching System Configuration to `flake.nix` {#switch-to-flake-nix}
|
|
|
|
After enabling the Flakes feature, the `sudo nixos-rebuild switch` command will prioritize reading the `/etc/nixos/flake.nix` file, and if it's not found, it will attempt to use `/etc/nixos/configuration.nix`.
|
|
|
|
You can start by using the official templates to learn how to write a flake.
|
|
First, check what templates are available:
|
|
|
|
```bash
|
|
nix flake show templates
|
|
```
|
|
|
|
Among them, the `templates#full` template demonstrates all possible usage. Take a look at its content:
|
|
|
|
```bash
|
|
nix flake init -t templates#full
|
|
cat flake.nix
|
|
```
|
|
|
|
Referencing this template, create the file `/etc/nixos/flake.nix` and write the configuration content. All subsequent system modifications will be taken over by Nix Flakes.
|
|
Here's an example of the content:
|
|
|
|
```nix{16}
|
|
{
|
|
description = "A simple NixOS flake";
|
|
|
|
inputs = {
|
|
# NixOS official package source, using the nixos-23.11 branch here
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
};
|
|
|
|
outputs = { self, nixpkgs, ... }@inputs: {
|
|
# Please replace my-nixos with your hostname
|
|
nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
# Import the previous configuration.nix we used,
|
|
# so the old configuration file still takes effect
|
|
./configuration.nix
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
Here we defined a system named `my-nixos`, with its configuration file located at `/etc/nixos/` as `./configuration.nix`. This means we are still using the old configuration.
|
|
|
|
Now, when you execute `sudo nixos-rebuild switch` to apply the configuration, the system should not change at all because we have simply switched to using Nix Flakes, and the configuration content remains consistent with before.
|
|
|
|
After the switch, we can manage the system through the Flakes feature.
|
|
|
|
Currently, our flake includes these files:
|
|
|
|
- `/etc/nixos/flake.nix`: The entrypoint for the flake, which is recognized and deployed when `sudo nixos-rebuild switch` is executed.
|
|
- `/etc/nixos/flake.lock`: The automatically generated version lock file, which records the data sources, hash values, and version numbers of all inputs in the entire flake, ensuring system reproducibility.
|
|
- `/etc/nixos/configuration.nix`: This is our previous configuration file, which is imported as a module in `flake.nix`. Currently, all system configurations are written in this file.
|
|
- `/etc/nixos/hardware-configuration.nix`: This is the system hardware configuration file, generated by NixOS, which describes the system's hardware information.
|
|
|
|
Up to this point, `/etc/nixos/flake.nix` has merely been a thin wrapper around `/etc/nixos/configuration.nix`, offering no new functionality and introducing no disruptive changes. In the content of the book that follows, we will gradually see the benefits that such a wrapper brings.
|
|
|
|
> Note: The configuration management method described in this book is NOT "Everything in a single file". It is recommended to categorize configuration content into different nix files, then introduce these configuration files in the `modules` list of `flake.nix`, and manage them with Git.
|
|
>
|
|
> The benefits of this approach are better organization of configuration files and improved maintainability of the configuration. The section [Modularizing NixOS Configuration](./modularize-the-configuration.md) will explain in detail how to modularize your NixOS configuration, and [Other Useful Tips - Managing NixOS Configuration with Git](./other-useful-tips.md) will introduce several best practices for managing NixOS configuration with Git.
|
|
|
|
|
|
## `flake.nix` Configuration Explained {#flake-nix-configuration-explained}
|
|
|
|
Above, we created a `flake.nix` file to manage system configurations, but you might still be unclear about its structure. Let's explain the content of this file in detail.
|
|
|
|
### 1. Flake Inputs
|
|
|
|
First, let's look at the `inputs` attribute. It is an attribute set that defines all the dependencies of this flake. These dependencies will be passed as arguments to the `outputs` function after they are fetched:
|
|
|
|
```nix{2-5,7}
|
|
{
|
|
inputs = {
|
|
# NixOS official package source, using the nixos-23.11 branch here
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
};
|
|
|
|
outputs = { self, nixpkgs, ... }@inputs: {
|
|
# Omitting previous configurations......
|
|
};
|
|
}
|
|
```
|
|
|
|
Dependencies in `inputs` has many types and definitions.
|
|
It can be another flake, a regular Git repository, or a local path.
|
|
The section [Other Usage of Flakes - Flake Inputs](../other-usage-of-flakes/inputs.md) describes common types of dependencies and their definitions in detail.
|
|
|
|
Here we only define a dependency named `nixpkgs`, which is the most common way to reference in a flake, i.e., `github:owner/name/reference`. The `reference` here can be a branch name, commit-id, or tag.
|
|
|
|
After `nixpkgs` is defined in `inputs`, you can use it in the parameters of the subsequent `outputs` function, which is exactly what our example does.
|
|
|
|
|
|
### 2. Flake Outputs
|
|
|
|
Now let's look at `outputs`.
|
|
It is a function that takes the dependencies from `inputs` as its parameters, and its return value is an attribute set, which represents the build results of the flake:
|
|
|
|
```nix{11-19}
|
|
{
|
|
description = "A simple NixOS flake";
|
|
|
|
inputs = {
|
|
# NixOS official package source, here using the nixos-23.11 branch
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
};
|
|
|
|
# The `self` parameter is special, it refers to
|
|
# the attribute set returned by the `outputs` function itself.
|
|
outputs = { self, nixpkgs, ... }@inputs: {
|
|
# The host with the hostname `my-nixos` will use this configuration
|
|
nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
./configuration.nix
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
Flakes can have various purposes and can have different types of outputs. The section [Flake Outputs](../other-usage-of-flakes/outputs.md) provides a more detailed introduction.
|
|
Here, we are only using the `nixosConfigurations` type of outputs, which is used to configure NixOS systems.
|
|
|
|
When we run the `sudo nixos-rebuild switch` command, it looks for the `nixosConfigurations.my-nixos` attribute (where `my-nixos` will be the hostname of your current system) in the attribute set returned by the `outputs` function of `/etc/nixos/flake.nix` and uses the definition there to configure your NixOS system.
|
|
|
|
Actually, we can also customize the location of the flake and the name of the NixOS configuration instead of using the defaults.
|
|
This can be done by adding the `--flake` parameter to the `nixos-rebuild` command. Here's an example:
|
|
|
|
```nix
|
|
sudo nixos-rebuild switch --flake /path/to/your/flake#your-hostname
|
|
```
|
|
|
|
A brief explanation of the `--flake /path/to/your/flake#your-hostname` parameter:
|
|
|
|
1. `/path/to/your/flake` is the location of the target flake. The default path is `/etc/nixos/`.
|
|
2. `#` is a separator, and `your-hostname` is the name of the NixOS configuration. `nixos-rebuild` will default to using the hostname of your current system as the configuration name to look for.
|
|
|
|
You can even directly reference a remote GitHub repository as your flake source, for example:
|
|
|
|
```nix
|
|
sudo nixos-rebuild switch --flake github:owner/repo#your-hostname
|
|
```
|
|
|
|
### 3. Simple Introduction to `nixpkgs.lib.nixosSystem` Function {#simple-introduction-to-nixpkgs-lib-nixos-system}
|
|
|
|
**A Flake can depend on other Flakes to utilize the features they provide.**
|
|
|
|
By default, a flake searches for a `flake.nix` file in the root directory of each of its dependencies (i.e., each item in `inputs`) and lazily evaluates their `outputs` functions. It then passes the attribute set returned by these functions as arguments to its own `outputs` function, enabling us to use the features provided by the other flakes within our current flake.
|
|
|
|
More precisely, the evaluation of the `outputs` function for each dependency is lazy. This means that a flake's `outputs` function is only evaluated when it is actually used, thereby avoiding unnecessary calculations and improving efficiency.
|
|
|
|
The description above may be a bit confusing, so let's take a look at the process with the `flake.nix` example used in this section.
|
|
Our `flake.nix` declares the `inputs.nixpkgs` dependency, so that [nixpkgs/flake.nix] will be evaluated when we run the `sudo nixos-rebuild switch` command.
|
|
|
|
From the source code of the Nixpkgs repository, we can see that its flake outputs definition includes the `lib` attribute, and in our example, we use the `lib` attribute's `nixosSystem` function to configure our NixOS system:
|
|
|
|
```nix{8-13}
|
|
{
|
|
inputs = {
|
|
# NixOS official package source, here using the nixos-23.11 branch
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
};
|
|
|
|
outputs = { self, nixpkgs, ... }@inputs: {
|
|
nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
./configuration.nix
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
The attribute set following `nixpkgs.lib.nixosSystem` is the function's parameter. We have only set two parameters here:
|
|
|
|
1. `system`: This is straightforward, it's the system architecture parameter.
|
|
2. `modules`: This is a list of modules, where the actual NixOS system configuration is defined.
|
|
The `/etc/nixos/configuration.nix` configuration file itself is a Nixpkgs Module, so it can be directly added to the `modules` list for use.
|
|
|
|
Understanding these basics is sufficient for beginners. Exploring the `nixpkgs.lib.nixosSystem` function in detail requires a grasp of the Nixpkgs module system.
|
|
Readers who have completed the [Modularizing NixOS Configuration](./modularize-the-configuration.md) section can return to [nixpkgs/flake.nix] to find the definition of `nixpkgs.lib.nixosSystem`, trace its source code, and study its implementation.
|
|
|
|
## Nixpkgs Module Structure Explained {#simple-introduction-to-nixpkgs-module-structure}
|
|
|
|
> The detailed workings of this module system will be introduced in the following [Modularizing NixOS Configuration](./modularize-the-configuration.md) section. Here, we'll just cover some basic knowledge.
|
|
|
|
|
|
You might be wondering why the `/etc/nixos/configuration.nix` configuration file adheres to the Nixpkgs Module definition and can be referenced directly within the `flake.nix`.
|
|
|
|
This is because the Nixpkgs repository contains a significant amount of NixOS implementation source code, primarily written in Nix. To manage and maintain such a large volume of Nix code and to allow users to customize various functions of their NixOS systems, a modular system for Nix code is essential.
|
|
|
|
This modular system for Nix code is also implemented within the Nixpkgs repository and is primarily used for modularizing NixOS system configurations. However, it is also widely used in other contexts, such as nix-darwin and home-manager.
|
|
Since NixOS is built on this modular system, it is only natural that its configuration files, including `/etc/nixos/configuration.nix`, are Nixpkgs Modules.
|
|
|
|
Before delving into the subsequent content, it's essential to have a basic understanding of how this module system operates.
|
|
|
|
Here's a simplified structure of a Nixpkgs Module:
|
|
|
|
```nix
|
|
{lib, config, options, pkgs, ...}:
|
|
{
|
|
# Importing other Modules
|
|
imports = [
|
|
# ...
|
|
./xxx.nix
|
|
];
|
|
for.bar.enable = true;
|
|
# Other option declarations
|
|
# ...
|
|
}
|
|
```
|
|
|
|
The definition is actually a Nix function, and it has five **automatically generated, automatically injected, and declaration-free parameters** provided by the module system:
|
|
|
|
1. `lib`: A built-in function library included with nixpkgs, offering many practical functions for operating Nix expressions.
|
|
- For more information, see <https://nixos.org/manual/nixpkgs/stable/#id-1.4>.
|
|
2. `config`: A set of all options' values in the current environment, which will be used extensively in the subsequent section on the module system.
|
|
3. `options`: A set of all options defined in all Modules in the current environment.
|
|
4. `pkgs`: A collection containing all nixpkgs packages, along with several related utility functions.
|
|
- At the beginner stage, you can consider its default value to be `nixpkgs.legacyPackages."${system}"`, and the value of `pkgs` can be customized through the `nixpkgs.pkgs` option.
|
|
5. `modulesPath`: A parameter available only in NixOS, which is a path pointing to [nixpkgs/nixos/modules](https://github.com/NixOS/nixpkgs/tree/nixos-23.11/nixos/modules).
|
|
- It is defined in [nixpkgs/nixos/lib/eval-config-minimal.nix#L43](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/lib/eval-config-minimal.nix#L43).
|
|
- It is typically used to import additional NixOS modules and can be found in most NixOS auto-generated `hardware-configuration.nix` files.
|
|
|
|
|
|
## Passing Non-default Parameters to Submodules {#pass-non-default-parameters-to-submodules}
|
|
|
|
If you need to pass other non-default parameters to submodules, you will need to use some special methods to manually specify these non-default parameters.
|
|
|
|
The Nixpkgs module system provides two ways to pass non-default parameters:
|
|
|
|
1. The `specialArgs` parameter of the `nixpkgs.lib.nixosSystem` function
|
|
2. Using the `_module.args` option in any module to pass parameters
|
|
|
|
The official documentation for these two parameters is buried deep and is vague and hard to understand. If readers are interested, I will include the links here:
|
|
|
|
1. `specialArgs`: There are scattered mentions related to it in the NixOS Manual and the Nixpkgs Manual.
|
|
- Nixpkgs Manual: [Module System - Nixpkgs]
|
|
- NixOS Manual: [nixpkgs/nixos-23.11/nixos/doc/manual/development/option-types.section.md#L237-L244]
|
|
1. `_module.args`: Its only official documentation is in the source code below.
|
|
- [nixpkgs/nixos-23.11/lib/modules.nix - _module.args]
|
|
|
|
In short, `specialArgs` and `_module.args` both require an attribute set as their value, and they serve the same purpose, passing all parameters in the attribute set to all submodules. The difference between them is:
|
|
|
|
1. The `_module.args` option can be used in any module to pass parameters to each other, which is more flexible than `specialArgs`, which can only be used in the `nixpkgs.lib.nixosSystem` function.
|
|
1. `_module.args` is declared within a module, so it must be evaluated after all modules have been evaluated before it can be used. This means that **if you use the parameters passed through `_module.args` in `imports = [ ... ];`, it will result in an `infinite recursion` error**. In this case, you must use `specialArgs` instead.
|
|
|
|
The NixOS community generally recommends prioritizing the use of the `_module.args` option and resorting to `specialArgs` only when `_module.args` cannot be used.
|
|
|
|
Suppose you want to pass a certain dependency to a submodule for use. You can use the `specialArgs` parameter to pass the `inputs` to all submodules:
|
|
|
|
```nix{13}
|
|
{
|
|
inputs = {
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
another-input.url = "github:username/repo-name/branch-name";
|
|
};
|
|
|
|
outputs = inputs@{ self, nixpkgs, another-input, ... }: {
|
|
nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
|
|
# Set all inputs parameters as special arguments for all submodules,
|
|
# so you can directly use all dependencies in inputs in submodules
|
|
specialArgs = { inherit inputs; };
|
|
modules = [
|
|
./configuration.nix
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
Or you can achieve the same effect using the `_module.args` option:
|
|
|
|
```nix{14}
|
|
{
|
|
inputs = {
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
another-input.url = "github:username/repo-name/branch-name";
|
|
};
|
|
outputs = inputs@{ self, nixpkgs, another-input, ... }: {
|
|
nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
./configuration.nix
|
|
{
|
|
# Set all inputs parameters as special arguments for all submodules,
|
|
# so you can directly use all dependencies in inputs in submodules
|
|
_module.args = { inherit inputs; };
|
|
}
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
Choose one of the two methods above to modify your configuration, and then you can use the `inputs` parameter in `/etc/nixos/configuration.nix`. The module system will automatically match the `inputs` defined in `specialArgs` and inject it into all submodules that require this parameter:
|
|
|
|
```nix{3}
|
|
# Nix will match by name and automatically inject the inputs
|
|
# from specialArgs/_module.args into the third parameter of this function
|
|
{ config, pkgs, inputs, ... }:
|
|
{
|
|
# ...
|
|
}
|
|
```
|
|
|
|
The next section will demonstrate how to use `specialArgs`/`_module.args` to install system software from other flake sources.
|
|
|
|
## Installing System Software from Other Flake Sources {#install-system-packages-from-other-flakes}
|
|
|
|
The most common requirement for managing a system is to install software, and we have already seen in the previous section how to install packages from the official nixpkgs repository using `environment.systemPackages`. These packages all come from the official nixpkgs repository.
|
|
|
|
Now, we will learn how to install software packages from other flake sources, which is much more flexible than installing directly from nixpkgs. The main use case is to install the latest version of a software that is not yet added or updated in Nixpkgs.
|
|
|
|
Taking the Helix editor as an example, here's how to compile and install the master branch of Helix directly.
|
|
|
|
First, add the helix input data source to `flake.nix`:
|
|
|
|
```nix{6,12,18}
|
|
{
|
|
inputs = {
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
|
|
|
# helix editor, use the master branch
|
|
helix.url = "github:helix-editor/helix/master";
|
|
};
|
|
|
|
outputs = inputs@{ self, nixpkgs, ... }: {
|
|
nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
specialArgs = { inherit inputs; };
|
|
modules = [
|
|
./configuration.nix
|
|
|
|
# This module works the same as the `specialArgs` parameter we used above
|
|
# chose one of the two methods to use
|
|
# { _module.args = { inherit inputs; };}
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
Next, you can reference this flake input data source in `configuration.nix`:
|
|
|
|
```nix{1,10}
|
|
{ config, pkgs, inputs, ... }:
|
|
{
|
|
# ...
|
|
environment.systemPackages = with pkgs; [
|
|
git
|
|
vim
|
|
wget
|
|
curl
|
|
# Here, the helix package is installed from the helix input data source
|
|
inputs.helix.packages."${pkgs.system}".helix
|
|
];
|
|
# ...
|
|
}
|
|
```
|
|
|
|
Make the necessary changes and deploy with `sudo nixos-rebuild switch`. The deployment will take much longer this time because Nix will compile the entire Helix program from source.
|
|
|
|
After deployment, you can directly test and verify the installation using the `hx` command in the terminal.
|
|
|
|
Additionally, if you just want to try out the latest version of Helix and decide whether to install it on your system later, there is a simpler way to do it in one command (but as mentioned earlier, compiling from source will take a long time):
|
|
|
|
```bash
|
|
nix run github:helix-editor/helix/master
|
|
```
|
|
|
|
We will go into more detail on the usage of `nix run` in the following section [Usage of the New CLI](../other-usage-of-flakes/the-new-cli.md).
|
|
|
|
|
|
## Leveraging Features from Other Flakes Packages
|
|
|
|
In fact, this is the primary functionality of Flakes — a flake can depend on other flakes, allowing it to utilize the features they provide. It's akin to how we incorporate functionalities from other libraries when writing programs in TypeScript, Go, Rust, and other programming languages.
|
|
|
|
The example above, using the latest version from the official Helix Flake, illustrates this functionality. More use cases will be discussed later, and here are a few examples referenced for future mention:
|
|
|
|
- [Getting Started with Home Manager](./start-using-home-manager.md): This introduces the community's Home-Manager as a dependency, enabling direct utilization of the features provided by this Flake.
|
|
- [Downgrading or Upgrading Packages](./downgrade-or-upgrade-packages.md): Here, different versions of Nixpkgs are introduced as dependencies, allowing for flexible selection of packages from various versions of Nixpkgs.
|
|
|
|
|
|
[nixpkgs/flake.nix]: https://github.com/NixOS/nixpkgs/tree/nixos-23.11/flake.nix
|
|
[nixpkgs/nixos/lib/eval-config.nix]: https://github.com/NixOS/nixpkgs/tree/nixos-23.11/nixos/lib/eval-config.nix
|
|
[Module System - Nixpkgs]: https://github.com/NixOS/nixpkgs/blob/23.11/doc/module-system/module-system.chapter.md
|
|
[nixpkgs/nixos-23.11/lib/modules.nix - _module.args]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/lib/modules.nix#L122-L184
|
|
[nixpkgs/nixos-23.11/nixos/doc/manual/development/option-types.section.md#L237-L244]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-types.section.md?plain=1#L237-L244
|