extern/nixos-and-flakes-book
1
0
Fork 0
mirror of https://github.com/ryan4yin/nixos-and-flakes-book.git synced 2024-11-22 08:03:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: finish 'best practices'

Browse Source
This commit is contained in:
Ryan Yin 2023-06-23 22:22:13 +08:00
parent 9db31c0d59
commit 02cb15d169
18 changed files with 885 additions and 849 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/.vitepress/config.ts
View File

@ -83,6 +83,24 @@ export default defineConfig({
{ text: "Overlays", link: "/nixpkgs/overlays.md" },
],
},
{
text: "Best Practices",
items: [
{ text: "Introduction", link: "/best-practices/intro.md" },
{
text: "Run downloaded binaries on NixOS",
link: "/best-practices/run-downloaded-binaries-on-nixos.md",
},
{
text: "Simplify NixOS-related Commands",
link: "/best-practices/simplify-nixos-related-commands.md",
},
{
text: "Debug with nix repl",
link: "/best-practices/debug-with-nix-repl.md",
},
],
},
],
socialLinks: [
@ -178,7 +196,21 @@ export default defineConfig({
},
{
text: "NixOS 最佳实践",
items: [{ text: "快速入门", link: "/zh/best-practices/index.md" }],
items: [
{ text: "简介", link: "/zh/best-practices/intro.md" },
{
text: "运行非 NixOS 的二进制文件",
link: "/zh/best-practices/run-downloaded-binaries-on-nixos.md",
},
{
text: "使用 Makefile 简化常用命令",
link: "/zh/best-practices/simplify-nixos-related-commands.md",
},
{
text: "使用 nix repl 查看源码、调试配置",
link: "/zh/best-practices/debug-with-nix-repl.md",
},
],
},
{
text: "Flakes 的其他玩法",

152
docs/best-practices/debug-with-nix-repl.md Normal file
View File

@ -0,0 +1,152 @@
## Debug with `nix repl`
We've used `nix repl '<nixpkgs>'` many times to check the source code in this guide, it's really a powerful tool to help us understand how things work in Nix.
Better take a look at the help message of `nix repl`:
```
› nix repl -f '<nixpkgs>'
Welcome to Nix 2.13.3. Type :? for help.
Loading installable ''...
Added 17755 variables.
nix-repl> :?
The following commands are available:
<expr> Evaluate and print expression
<x> = <expr> Bind expression to variable
:a <expr> Add attributes from resulting set to scope
:b <expr> Build a derivation
:bl <expr> Build a derivation, creating GC roots in the working directory
:e <expr> Open package or function in $EDITOR
:i <expr> Build derivation, then install result into current profile
:l <path> Load Nix expression and add it to scope
:lf <ref> Load Nix flake and add it to scope
:p <expr> Evaluate and print expression recursively
:q Exit nix-repl
:r Reload all files
:sh <expr> Build dependencies of derivation, then start nix-shell
:t <expr> Describe result of evaluation
:u <expr> Build derivation, then start nix-shell
:doc <expr> Show documentation of a builtin function
:log <expr> Show logs for a derivation
:te [bool] Enable, disable or toggle showing traces for errors
```
Some expressions that I use frequently: `:lf <ref>`, `:e <expr>`.
`:e <expr>` is very intuitive, so I won't repeat it. let's take a look at `:lf <ref>`:
```nix
# cd into my nix-config repo(you should replace it with your own nix-config repo)
› cd ~/nix-config/
# enter nix repl
› nix repl
Welcome to Nix 2.13.3. Type :? for help.
# load my nix flake and add it to scope
nix-repl> :lf .
Added 16 variables.
# press <TAB> to see what we have in scope
nix-repl><TAB>
# ......omit some outputs
__isInt nixosConfigurations
__isList null
__isPath outPath
__isString outputs
__langVersion packages
# ......omit some outputs
# check what's in inputs
nix-repl> inputs.<TAB>
inputs.agenix inputs.nixpkgs
inputs.darwin inputs.nixpkgs-darwin
inputs.home-manager inputs.nixpkgs-unstable
inputs.hyprland inputs.nixpkgs-wayland
inputs.nil
inputs.nixos-generators
# check what's in inputs.nil
nix-repl> inputs.nil.packages.
inputs.nil.packages.aarch64-darwin
inputs.nil.packages.aarch64-linux
inputs.nil.packages.x86_64-darwin
inputs.nil.packages.x86_64-linux
# check the outputs of my nix flake
nix-repl> outputs.nixosConfigurations.<TAB>
outputs.nixosConfigurations.ai
outputs.nixosConfigurations.aquamarine
outputs.nixosConfigurations.kana
outputs.nixosConfigurations.ruby
nix-repl> outputs.nixosConfigurations.ai.<TAB>
outputs.nixosConfigurations.ai._module
outputs.nixosConfigurations.ai._type
outputs.nixosConfigurations.ai.class
outputs.nixosConfigurations.ai.config
outputs.nixosConfigurations.ai.extendModules
outputs.nixosConfigurations.ai.extraArgs
outputs.nixosConfigurations.ai.options
outputs.nixosConfigurations.ai.pkgs
outputs.nixosConfigurations.ai.type
nix-repl> outputs.nixosConfigurations.ai.config.
outputs.nixosConfigurations.ai.config.age
outputs.nixosConfigurations.ai.config.appstream
outputs.nixosConfigurations.ai.config.assertions
outputs.nixosConfigurations.ai.config.boot
outputs.nixosConfigurations.ai.config.console
outputs.nixosConfigurations.ai.config.containers
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activation
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activationPackage
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.emptyActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableDebugInfo
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableNixpkgsReleaseCheck
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraBuilderCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraOutputsToInstall
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraProfileCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.BROWSER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.DELTA_PAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.EDITOR
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.GLFW_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.MANPAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.QT_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
# ......omit other outputs
# check the value of `TERM`
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
"xterm-256color"
# check all files defined by `home.file`
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bash_profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bashrc
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile-bak
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/config
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/i3blocks.conf
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/keybindings
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/layouts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/scripts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/wallpaper.png
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/rofi
#......
```
As you can see, we can check every attribute of my flake in the REPL after loading it, which is very convenient for debugging.

351
docs/best-practices/index.md
View File

@ -1,351 +0,0 @@
Nix is powerful and flexible, it provides a lot of ways to do things, making it difficult to find the most suitable way to do your job.
Here are some best practices that I've learned from the community, hope it can help you.
## 1. Run downloaded binaries on NixOS
NixOS does not follow the FHS standard, so the binaries you download from the Internet will not likely work on NixOS. But there are some ways to make it work.
Here is a detailed guide which provides 10 ways to run downloaded binaries on NixOS: [Different methods to run a non-nixos executable on Nixos](https://unix.stackexchange.com/questions/522822/different-methods-to-run-a-non-nixos-executable-on-nixos), I recommend you to read it.
Among these methods, I prefer creating a FHS environment to run the binary, which is very convenient and easy to use.
To create such an environment, add the following code to one of your nix modules:
```nix
{ config, pkgs, lib, ... }:
{
# ......omit many configurations
environment.systemPackages = with pkgs; [
# ......omit many packages
# create a fhs environment by command `fhs`, so we can run non-nixos packages in nixos!
(pkgs.buildFHSUserEnv (base // {
name = "fhs";
targetPkgs = pkgs: (
# pkgs.buildFHSUserEnv provides only a minimal fhs environment,
# it lacks many basic packages needed by most softwares.
# so we need to add them manually.
#
# pkgs.appimageTools provides basic packages needed by most softwares.
(pkgs.appimageTools.defaultFhsEnvArgs.targetPkgs pkgs) ++ with pkgs; [
pkg-config
ncurses
# feel free to add more packages here, if you need
]
);
profile = "export FHS=1";
runScript = "bash";
extraOutputsToInstall = ["dev"];
}))
];
# ......omit many configurations
}
```
after applying the updated configuration, you can run `fhs` to enter the FHS environment, and then run the binary you downloaded, e.g.
```shell
# Activating FHS drops me in a shell which looks like a "normal" Linux
$ fhs
# check what we have in /usr/bin
(fhs) $ ls /usr/bin
# try to run a non-nixos binary downloaded from the Internet
(fhs) $ ./bin/code
```
## 2. check the source code and debug with `nix repl`
We've used `nix repl '<nixpkgs>'` many times to check the source code in this guide, it's really a powerful tool to help us understand how things work in Nix.
Better take a look at the help message of `nix repl`:
```
› nix repl -f '<nixpkgs>'
Welcome to Nix 2.13.3. Type :? for help.
Loading installable ''...
Added 17755 variables.
nix-repl> :?
The following commands are available:
<expr> Evaluate and print expression
<x> = <expr> Bind expression to variable
:a <expr> Add attributes from resulting set to scope
:b <expr> Build a derivation
:bl <expr> Build a derivation, creating GC roots in the working directory
:e <expr> Open package or function in $EDITOR
:i <expr> Build derivation, then install result into current profile
:l <path> Load Nix expression and add it to scope
:lf <ref> Load Nix flake and add it to scope
:p <expr> Evaluate and print expression recursively
:q Exit nix-repl
:r Reload all files
:sh <expr> Build dependencies of derivation, then start nix-shell
:t <expr> Describe result of evaluation
:u <expr> Build derivation, then start nix-shell
:doc <expr> Show documentation of a builtin function
:log <expr> Show logs for a derivation
:te [bool] Enable, disable or toggle showing traces for errors
```
Some expressions that I use frequently: `:lf <ref>`, `:e <expr>`.
`:e <expr>` is very intuitive, so I won't repeat it. let's take a look at `:lf <ref>`:
```nix
# cd into my nix-config repo(you should replace it with your own nix-config repo)
› cd ~/nix-config/
# enter nix repl
› nix repl
Welcome to Nix 2.13.3. Type :? for help.
# load my nix flake and add it to scope
nix-repl> :lf .
Added 16 variables.
# press <TAB> to see what we have in scope
nix-repl><TAB>
# ......omit some outputs
__isInt nixosConfigurations
__isList null
__isPath outPath
__isString outputs
__langVersion packages
# ......omit some outputs
# check what's in inputs
nix-repl> inputs.<TAB>
inputs.agenix inputs.nixpkgs
inputs.darwin inputs.nixpkgs-darwin
inputs.home-manager inputs.nixpkgs-unstable
inputs.hyprland inputs.nixpkgs-wayland
inputs.nil
inputs.nixos-generators
# check what's in inputs.nil
nix-repl> inputs.nil.packages.
inputs.nil.packages.aarch64-darwin
inputs.nil.packages.aarch64-linux
inputs.nil.packages.x86_64-darwin
inputs.nil.packages.x86_64-linux
# check the outputs of my nix flake
nix-repl> outputs.nixosConfigurations.<TAB>
outputs.nixosConfigurations.ai
outputs.nixosConfigurations.aquamarine
outputs.nixosConfigurations.kana
outputs.nixosConfigurations.ruby
nix-repl> outputs.nixosConfigurations.ai.<TAB>
outputs.nixosConfigurations.ai._module
outputs.nixosConfigurations.ai._type
outputs.nixosConfigurations.ai.class
outputs.nixosConfigurations.ai.config
outputs.nixosConfigurations.ai.extendModules
outputs.nixosConfigurations.ai.extraArgs
outputs.nixosConfigurations.ai.options
outputs.nixosConfigurations.ai.pkgs
outputs.nixosConfigurations.ai.type
nix-repl> outputs.nixosConfigurations.ai.config.
outputs.nixosConfigurations.ai.config.age
outputs.nixosConfigurations.ai.config.appstream
outputs.nixosConfigurations.ai.config.assertions
outputs.nixosConfigurations.ai.config.boot
outputs.nixosConfigurations.ai.config.console
outputs.nixosConfigurations.ai.config.containers
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activation
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activationPackage
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.emptyActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableDebugInfo
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableNixpkgsReleaseCheck
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraBuilderCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraOutputsToInstall
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraProfileCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.BROWSER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.DELTA_PAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.EDITOR
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.GLFW_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.MANPAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.QT_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
# ......omit other outputs
# check the value of `TERM`
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
"xterm-256color"
# check all files defined by `home.file`
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bash_profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bashrc
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile-bak
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/config
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/i3blocks.conf
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/keybindings
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/layouts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/scripts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/wallpaper.png
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/rofi
#......
```
As you can see, we can check every attribute of my flake in the REPL after loading it, which is very convenient for debugging.
## 3. Remote deployment
Some tools like [NixOps](https://github.com/NixOS/nixops), [deploy-rs](https://github.com/serokell/deploy-rs), and [colmena](https://github.com/zhaofengli/colmena) can all be used to deploy NixOS configuration to remote hosts, but they are all too complicated for me, so skip them all.
`nixos-rebuild`, the tool we use to deploy NixOS configuration, also supports remote deployment through ssh protocol, which is very convenient and simple.
But `nixos-rebuild` does not support deploying with password authentication, so to use it for remote deployment, we need to:
1. Configure ssh public key authentication for the remote hosts.
2. To avoid sudo password verification failures, we need to use the `root` user to deploy, or grant the user sudo permission without password verification.
1. related issue: <https://github.com/NixOS/nixpkgs/issues/118655>
After the above configuration is completed, we can deploy the configuration to the server through the following command:
```bash
# 1. add the ssh key to ssh-agent first
ssh-add ~/.ssh/ai-idols
# 2. deploy the configuration to the remote host, using the ssh key we added in step 1
# and the username defaults to `$USER`, it's `ryan` in my case.
nixos-rebuild --flake .#aquamarine --target-host 192.168.4.1 --build-host 192.168.4.1 switch --use-remote-sudo --verbose
```
The commands above will build & deploy the configuration to aquamarine, the build process will be executed on aquamarine too,
and the `--use-remote-sudo` option indicates that we need to use sudo permission on the remote server to deploy the configuration.
If you want to build the configuration locally and deploy it to the remote server, just replace `--build-host aquamarinr` with `--build-host localhost`.
Instead of use ip address directly, we can also define some host aliases in `~/.ssh/config` or `/etc/ssh/ssh_config`, for example:
> ssh's config can be generated completely through Nix configuration, and this task is left to you.
```bash
› cat ~/.ssh/config
# ......
Host ai
HostName 192.168.5.100
Port 22
Host aquamarine
HostName 192.168.5.101
Port 22
Host ruby
HostName 192.168.5.102
Port 22
Host kana
HostName 192.168.5.103
Port 22
```
Then we can use the host alias to deploy the configuration:
```bash
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --verbose
```
## 4. Work with Makefile
> NOTE: Makefile's target name should not be the same as one of the file or directory in the current directory, otherwise the target will not be executed!
I use Makefile to manage the commands of my flake, which is very convenient.
For example, my Makefile looks like this:
```makefile
#
# NOTE: Makefile's target name should not be the same as one of the file or directory in the current directory,
# otherwise the target will not be executed!
#
############################################################################
#
# Nix commands related to the local machine
#
############################################################################
deploy:
nixos-rebuild switch --flake . --use-remote-sudo
debug:
nixos-rebuild switch --flake . --use-remote-sudo --show-trace --verbose
update:
nix flake update
history:
nix profile history --profile /nix/var/nix/profiles/system
gc:
# remove all generations older than 7 days
sudo nix profile wipe-history --profile /nix/var/nix/profiles/system --older-than 7d
# garbage collect all unused nix store entries
sudo nix store gc --debug
############################################################################
#
# Idols, Commands related to my remote distributed building cluster
#
############################################################################
add-idols-ssh-key:
ssh-add ~/.ssh/ai-idols
aqua: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo
aqua-debug: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --show-trace --verbose
ruby: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo
ruby-debug: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo --show-trace --verbose
kana: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo
kana-debug: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo --show-trace --verbose
idols: aqua ruby kana
idols-debug: aqua-debug ruby-debug kana-debug
```
Save the above Makefile to the root directory of the flake, and then we can use `make deploy` to deploy the configuration to the local machine, and use `make idols` to deploy the configuration to all my remote servers.
## References
- [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse]
[Tips&Tricks for NixOS Desktop - NixOS Discourse]: https://discourse.nixos.org/t/tips-tricks-for-nixos-desktop/28488

11
docs/best-practices/intro.md Normal file
View File

@ -0,0 +1,11 @@
Nix is powerful and flexible, it provides a lot of ways to do things, making it difficult to find the most suitable way to do your job.
Here are some best practices that I've learned from the community, hope it can help you.
## 4.
## References
- [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse]
[Tips&Tricks for NixOS Desktop - NixOS Discourse]: https://discourse.nixos.org/t/tips-tricks-for-nixos-desktop/28488

60
docs/best-practices/remote-deployment.md Normal file
View File

@ -0,0 +1,60 @@
## Remote deployment
Some tools like [NixOps](https://github.com/NixOS/nixops), [deploy-rs](https://github.com/serokell/deploy-rs), and [colmena](https://github.com/zhaofengli/colmena) can all be used to deploy NixOS configuration to remote hosts, but they are all too complicated for me.
`nixos-rebuild`, the tool we use to deploy NixOS configuration, also supports remote deployment through ssh protocol, which is very convenient and simple.
But `nixos-rebuild` does not support deploying with password authentication, so to use it for remote deployment, we need to:
1. Configure ssh public key authentication for the remote hosts.
2. To avoid sudo password verification failures, we need to use the `root` user to deploy, or grant the user sudo permission without password verification.
1. related issue: <https://github.com/NixOS/nixpkgs/issues/118655>
After the above configuration is completed, we can deploy the configuration to the server through the following command:
```bash
# 1. add the ssh key to ssh-agent first
ssh-add ~/.ssh/ai-idols
# 2. deploy the configuration to the remote host, using the ssh key we added in step 1
# and the username defaults to `$USER`, it's `ryan` in my case.
nixos-rebuild --flake .#aquamarine --target-host 192.168.4.1 --build-host 192.168.4.1 switch --use-remote-sudo --verbose
```
The commands above will build & deploy the configuration to aquamarine, the build process will be executed on aquamarine too,
and the `--use-remote-sudo` option indicates that we need to use sudo permission on the remote server to deploy the configuration.
If you want to build the configuration locally and deploy it to the remote server, just replace `--build-host aquamarinr` with `--build-host localhost`.
Instead of use ip address directly, we can also define some host aliases in `~/.ssh/config` or `/etc/ssh/ssh_config`, for example:
> ssh's config can be generated completely through Nix configuration, and this task is left to you.
```bash
› cat ~/.ssh/config
# ......
Host ai
HostName 192.168.5.100
Port 22
Host aquamarine
HostName 192.168.5.101
Port 22
Host ruby
HostName 192.168.5.102
Port 22
Host kana
HostName 192.168.5.103
Port 22
```
Then we can use the host alias to deploy the configuration:
```bash
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --verbose
```

58
docs/best-practices/run-downloaded-binaries-on-nixos.md Normal file
View File

@ -0,0 +1,58 @@
## Run downloaded binaries on NixOS
NixOS does not follow the FHS standard, so the binaries you download from the Internet will not likely work on NixOS. But there are some ways to make it work.
Here is a detailed guide which provides 10 ways to run downloaded binaries on NixOS: [Different methods to run a non-nixos executable on Nixos](https://unix.stackexchange.com/questions/522822/different-methods-to-run-a-non-nixos-executable-on-nixos), I recommend you to read it.
Among these methods, I prefer creating a FHS environment to run the binary, which is very convenient and easy to use.
To create such an environment, add the following code to one of your nix modules:
```nix
{ config, pkgs, lib, ... }:
{
# ......omit many configurations
environment.systemPackages = with pkgs; [
# ......omit many packages
# create a fhs environment by command `fhs`, so we can run non-nixos packages in nixos!
(pkgs.buildFHSUserEnv (base // {
name = "fhs";
targetPkgs = pkgs: (
# pkgs.buildFHSUserEnv provides only a minimal fhs environment,
# it lacks many basic packages needed by most softwares.
# so we need to add them manually.
#
# pkgs.appimageTools provides basic packages needed by most softwares.
(pkgs.appimageTools.defaultFhsEnvArgs.targetPkgs pkgs) ++ with pkgs; [
pkg-config
ncurses
# feel free to add more packages here, if you need
]
);
profile = "export FHS=1";
runScript = "bash";
extraOutputsToInstall = ["dev"];
}))
];
# ......omit many configurations
}
```
after applying the updated configuration, you can run `fhs` to enter the FHS environment, and then run the binary you downloaded, e.g.
```shell
# Activating FHS drops me in a shell which looks like a "normal" Linux
$ fhs
# check what we have in /usr/bin
(fhs) $ ls /usr/bin
# try to run a non-nixos binary downloaded from the Internet
(fhs) $ ./bin/code
```
## References
- [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse]: Just as the title says, it is a collection of tips and tricks for NixOS desktop.

72
docs/best-practices/simplify-nixos-related-commands.md Normal file
View File

@ -0,0 +1,72 @@
## Simplify nixos-related commands
I use Makefile to simplify nixos-related commands, which is very convenient.
You can also use other similar tools to do this job, here I will only introduce my usage as a reference.
My Makefile looks like this:
```makefile
#
# NOTE: Makefile's target name should not be the same as one of the file or directory in the current directory,
# otherwise the target will not be executed!
#
############################################################################
#
# Nix commands related to the local machine
#
############################################################################
deploy:
nixos-rebuild switch --flake . --use-remote-sudo
debug:
nixos-rebuild switch --flake . --use-remote-sudo --show-trace --verbose
update:
nix flake update
history:
nix profile history --profile /nix/var/nix/profiles/system
gc:
# remove all generations older than 7 days
sudo nix profile wipe-history --profile /nix/var/nix/profiles/system --older-than 7d
# garbage collect all unused nix store entries
sudo nix store gc --debug
############################################################################
#
# Idols, Commands related to my remote distributed building cluster
#
############################################################################
add-idols-ssh-key:
ssh-add ~/.ssh/ai-idols
aqua: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo
aqua-debug: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --show-trace --verbose
ruby: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo
ruby-debug: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo --show-trace --verbose
kana: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo
kana-debug: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo --show-trace --verbose
idols: aqua ruby kana
idols-debug: aqua-debug ruby-debug kana-debug
```
Save the above Makefile to the root directory of the flake, and then we can use `make deploy` to deploy the configuration to the local machine, and use `make idols` to deploy the configuration to all my remote servers.

153
docs/zh/best-practices/debug-with-nix-repl.md Normal file
View File

@ -0,0 +1,153 @@
## 通过 `nix repl` 查看源码、调试配置 {#view-source-code-via-nix-repl}
前面我们已经使用 `nix repl '<nixpkgs>'` 看过很多次源码了，这是一个非常强大的工具，可以帮助我们理解 Nix 的工作原理。
要学会用 `nix repl`，最好先看看它的 help 信息：
```
› nix repl -f '<nixpkgs>'
Welcome to Nix 2.13.3. Type :? for help.
Loading installable ''...
Added 17755 variables.
nix-repl> :?
The following commands are available:
<expr> Evaluate and print expression
<x> = <expr> Bind expression to variable
:a <expr> Add attributes from resulting set to scope
:b <expr> Build a derivation
:bl <expr> Build a derivation, creating GC roots in the working directory
:e <expr> Open package or function in $EDITOR
:i <expr> Build derivation, then install result into current profile
:l <path> Load Nix expression and add it to scope
:lf <ref> Load Nix flake and add it to scope
:p <expr> Evaluate and print expression recursively
:q Exit nix-repl
:r Reload all files
:sh <expr> Build dependencies of derivation, then start nix-shell
:t <expr> Describe result of evaluation
:u <expr> Build derivation, then start nix-shell
:doc <expr> Show documentation of a builtin function
:log <expr> Show logs for a derivation
:te [bool] Enable, disable or toggle showing traces for errors
```
我最常用的命令是 `:lf <ref>` 跟 `:e <expr>`.
`:e <expr>` 非常直观，所以这里不再赘述，我们来看看 `:lf <ref>`：
```nix
# 进入我的 nix 配置目录（建议替换成你自己的配置目录）
› cd ~/nix-config/
# 进入 nix repl 解释器
› nix repl
Welcome to Nix 2.13.3. Type :? for help.
# 将我的 nix 配置作为一个 flake 加载到当前作用域中
nix-repl> :lf .
Added 16 variables.
# 按 <TAB> 看看当前作用域中有哪些变量，果然 nixosConfigurations inputs outputs 跟 packages 都在里面
# 这意味着我们可以很方便地检查这些配置的内部状态
nix-repl><TAB>
# ......omit some outputs
__isInt nixosConfigurations
__isList null
__isPath outPath
__isString outputs
__langVersion packages
# ......omit some outputs
# 看看 inputs 里都有些啥
nix-repl> inputs.<TAB>
inputs.agenix inputs.nixpkgs
inputs.darwin inputs.nixpkgs-darwin
inputs.home-manager inputs.nixpkgs-unstable
inputs.hyprland inputs.nixpkgs-wayland
inputs.nil
inputs.nixos-generators
# 看看 inputs.nil.packages 里都有些啥
nix-repl> inputs.nil.packages.
inputs.nil.packages.aarch64-darwin
inputs.nil.packages.aarch64-linux
inputs.nil.packages.x86_64-darwin
inputs.nil.packages.x86_64-linux
# 看看 outputs 里都有些啥
nix-repl> outputs.nixosConfigurations.<TAB>
outputs.nixosConfigurations.ai
outputs.nixosConfigurations.aquamarine
outputs.nixosConfigurations.kana
outputs.nixosConfigurations.ruby
# 看看 ai 的配置都有些啥
nix-repl> outputs.nixosConfigurations.ai.<TAB>
outputs.nixosConfigurations.ai._module
outputs.nixosConfigurations.ai._type
outputs.nixosConfigurations.ai.class
outputs.nixosConfigurations.ai.config
outputs.nixosConfigurations.ai.extendModules
outputs.nixosConfigurations.ai.extraArgs
outputs.nixosConfigurations.ai.options
outputs.nixosConfigurations.ai.pkgs
outputs.nixosConfigurations.ai.type
nix-repl> outputs.nixosConfigurations.ai.config.
outputs.nixosConfigurations.ai.config.age
outputs.nixosConfigurations.ai.config.appstream
outputs.nixosConfigurations.ai.config.assertions
outputs.nixosConfigurations.ai.config.boot
outputs.nixosConfigurations.ai.config.console
outputs.nixosConfigurations.ai.config.containers
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activation
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activationPackage
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.emptyActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableDebugInfo
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableNixpkgsReleaseCheck
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraBuilderCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraOutputsToInstall
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraProfileCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.BROWSER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.DELTA_PAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.EDITOR
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.GLFW_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.MANPAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.QT_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
# ......omit other outputs
# 看看 `TERM` 这个环境变量的值是啥
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
"xterm-256color"
# 看下我使用 `home.file` 定义的所有文件
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bash_profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bashrc
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile-bak
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/config
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/i3blocks.conf
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/keybindings
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/layouts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/scripts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/wallpaper.png
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/rofi
#......
```
能看到，通过 `nix repl` 加载好我的 flake 配置后，就能很方便地检查所有的配置项了，这对于调试非常有用。

346
docs/zh/best-practices/index.md
View File

@ -1,346 +0,0 @@
## 十一、最佳实践 {#best-practices}
> [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse]
Nix 非常强大且灵活，做一件事有非常多的方法，这就导致了很难找到最合适的方法来做你的工作。
这里记录了一些我在使用 NixOS 中学习到的最佳实践，希望能帮到你。
### 1. 运行非 NixOS 的二进制文件 {#run-non-nixos-binaries}
NixOS 不遵循 FHS 标准，因此你从网上下载的二进制程序在 NixOS 上大概率是跑不了的。
为了在 NixOS 上跑这些非 NixOS 的二进制程序，需要做一些骚操作。有位老兄在这里总结了 10 种实现此目的的方法：[Different methods to run a non-nixos executable on Nixos](https://unix.stackexchange.com/questions/522822/different-methods-to-run-a-non-nixos-executable-on-nixos)，推荐一读。
我个人用的比较多的方法是，直接创建一个 FHS 环境来运行二进制程序，这种方法非常方便易用。
大概玩法是这样的，首先在你的 `environment.systemPackages` 中添加这个包：
```nix
{ config, pkgs, lib, ... }:
{
# ......
environment.systemPackages = with pkgs; [
# ......o
# create a fhs environment by command `fhs`, so we can run non-nixos packages in nixos!
(pkgs.buildFHSUserEnv (base // {
name = "fhs";
targetPkgs = pkgs: (
# pkgs.buildFHSUserEnv 只提供一个最小的 FHS 环境，缺少很多常用软件所必须的基础包
# 所以直接使用它很可能会报错
#
# pkgs.appimageTools 提供了大多数程序常用的基础包，所以我们可以直接用它来补充
(pkgs.appimageTools.defaultFhsEnvArgs.targetPkgs pkgs) ++ with pkgs; [
pkg-config
ncurses
# 如果你的 FHS 程序还有其他依赖，把它们添加在这里
]
);
profile = "export FHS=1";
runScript = "bash";
extraOutputsToInstall = ["dev"];
}))
];
# ......
}
```
部署好上面的配置后，你就能用 `fhs` 命令进入我们定义好的 FHS 环境了，然后就可以运行你下载的二进制程序了，比如：
```shell
# 进入我们定义好的 fhs 环境，它就跟其他 Linux 发行版一样了
$ fhs
# 看看我们的 /usr/bin 里是不是多了很多东西
(fhs) $ ls /usr/bin
# 尝试下跑一个非 nixos 的二进制程序
(fhs) $ ./bin/code
```
### 2. 通过 `nix repl` 查看源码、调试配置 {#view-source-code-via-nix-repl}
前面我们已经使用 `nix repl '<nixpkgs>'` 看过很多次源码了，这是一个非常强大的工具，可以帮助我们理解 Nix 的工作原理。
要学会用 `nix repl`，最好先看看它的 help 信息：
```
› nix repl -f '<nixpkgs>'
Welcome to Nix 2.13.3. Type :? for help.
Loading installable ''...
Added 17755 variables.
nix-repl> :?
The following commands are available:
<expr> Evaluate and print expression
<x> = <expr> Bind expression to variable
:a <expr> Add attributes from resulting set to scope
:b <expr> Build a derivation
:bl <expr> Build a derivation, creating GC roots in the working directory
:e <expr> Open package or function in $EDITOR
:i <expr> Build derivation, then install result into current profile
:l <path> Load Nix expression and add it to scope
:lf <ref> Load Nix flake and add it to scope
:p <expr> Evaluate and print expression recursively
:q Exit nix-repl
:r Reload all files
:sh <expr> Build dependencies of derivation, then start nix-shell
:t <expr> Describe result of evaluation
:u <expr> Build derivation, then start nix-shell
:doc <expr> Show documentation of a builtin function
:log <expr> Show logs for a derivation
:te [bool] Enable, disable or toggle showing traces for errors
```
我最常用的命令是 `:lf <ref>` 跟 `:e <expr>`.
`:e <expr>` 非常直观，所以这里不再赘述，我们来看看 `:lf <ref>`：
```nix
# 进入我的 nix 配置目录（建议替换成你自己的配置目录）
› cd ~/nix-config/
# 进入 nix repl 解释器
› nix repl
Welcome to Nix 2.13.3. Type :? for help.
# 将我的 nix 配置作为一个 flake 加载到当前作用域中
nix-repl> :lf .
Added 16 variables.
# 按 <TAB> 看看当前作用域中有哪些变量，果然 nixosConfigurations inputs outputs 跟 packages 都在里面
# 这意味着我们可以很方便地检查这些配置的内部状态
nix-repl><TAB>
# ......omit some outputs
__isInt nixosConfigurations
__isList null
__isPath outPath
__isString outputs
__langVersion packages
# ......omit some outputs
# 看看 inputs 里都有些啥
nix-repl> inputs.<TAB>
inputs.agenix inputs.nixpkgs
inputs.darwin inputs.nixpkgs-darwin
inputs.home-manager inputs.nixpkgs-unstable
inputs.hyprland inputs.nixpkgs-wayland
inputs.nil
inputs.nixos-generators
# 看看 inputs.nil.packages 里都有些啥
nix-repl> inputs.nil.packages.
inputs.nil.packages.aarch64-darwin
inputs.nil.packages.aarch64-linux
inputs.nil.packages.x86_64-darwin
inputs.nil.packages.x86_64-linux
# 看看 outputs 里都有些啥
nix-repl> outputs.nixosConfigurations.<TAB>
outputs.nixosConfigurations.ai
outputs.nixosConfigurations.aquamarine
outputs.nixosConfigurations.kana
outputs.nixosConfigurations.ruby
# 看看 ai 的配置都有些啥
nix-repl> outputs.nixosConfigurations.ai.<TAB>
outputs.nixosConfigurations.ai._module
outputs.nixosConfigurations.ai._type
outputs.nixosConfigurations.ai.class
outputs.nixosConfigurations.ai.config
outputs.nixosConfigurations.ai.extendModules
outputs.nixosConfigurations.ai.extraArgs
outputs.nixosConfigurations.ai.options
outputs.nixosConfigurations.ai.pkgs
outputs.nixosConfigurations.ai.type
nix-repl> outputs.nixosConfigurations.ai.config.
outputs.nixosConfigurations.ai.config.age
outputs.nixosConfigurations.ai.config.appstream
outputs.nixosConfigurations.ai.config.assertions
outputs.nixosConfigurations.ai.config.boot
outputs.nixosConfigurations.ai.config.console
outputs.nixosConfigurations.ai.config.containers
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activation
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.activationPackage
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.emptyActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableDebugInfo
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.enableNixpkgsReleaseCheck
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraActivationPath
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraBuilderCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraOutputsToInstall
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.extraProfileCommands
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file
# ......omit other outputs
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.BROWSER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.DELTA_PAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.EDITOR
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.GLFW_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.MANPAGER
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.QT_IM_MODULE
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
# ......omit other outputs
# 看看 `TERM` 这个环境变量的值是啥
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.sessionVariables.TERM
"xterm-256color"
# 看下我使用 `home.file` 定义的所有文件
nix-repl> outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file.<TAB>
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bash_profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..bashrc
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/fcitx5/profile-bak
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/config
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/i3blocks.conf
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/keybindings
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/layouts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/scripts
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/i3/wallpaper.png
outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/rofi
#......
```
能看到，通过 `nix repl` 加载好我的 flake 配置后，就能很方便地检查所有的配置项了，这对于调试非常有用。
### 3. 远程部署
社区的一些工具，比如 [NixOps](https://github.com/NixOS/nixops), [deploy-rs](https://github.com/serokell/deploy-rs), 跟 [colmena](https://github.com/zhaofengli/colmena)，都可以用来部署 NixOS 配置到远程主机，但是都太复杂了，所以先全部跳过。
实际上我们前面使用了多次的 NixOS 本机部署命令 `nixos-rebuild`，这个工具也支持通过 ssh 协议进行远程部署，非常方便。
美中不足的是，`nixos-rebuild` 不支持使用密码认证进行部署，所以要想使用它进行远程部署，我们需要：
1. 为远程主机配置 ssh 公钥认证。
2. 为了避免 sudo 密码认证失败，需要使用 `root` 用户进行部署，或者给用户授予 sudo 权限不需要密码认证。
1. 相关 issue: <https://github.com/NixOS/nixpkgs/issues/118655>
在搞定上面两点后，我们就可以使用 `nixos-rebuild` 进行远程部署了：
```bash
# 1. 首先将本地的 ssh 私钥加载到 ssh-agent 中，以便后续使用
ssh-add ~/.ssh/ai-idols
# 2. 将 NixOS 配置部署到远程主机，使用第一步添加的 ssh key 进行认证，用户名默认为 `$USER`
nixos-rebuild --flake .#aquamarine --target-host 192.168.4.1 --build-host 192.168.4.1 switch --use-remote-sudo --verbose
```
上面的命令会将 NixOS 配置部署到 `aquamarine` 这台主机上，参数解释如下：
1. `--target-host`: 设置远程主机的 ip 地址
2. `--build-host` 指定了构建 NixOS 配置的主机，这里设置为跟 `--target-host` 相同，表示在远程主机上构建配置。
3. `--use-remote-sudo` 表示部署需要用到远程主机的 sudo 权限，如果不设置这个参数，部署会失败。
如果你希望在本地构建配置，然后再部署到远程主机，可以命令中的 `--build-host aquamarinr` 替换为 `--build-host localhost`。
另外如果你不想直接使用 ip 地址，可以在 `~/.ssh/config` 或者 `/etc/ssh/ssh_config` 中定义一些主机别名，比如：
> 当然如下这份配置也完全可以通过 Nix 来管理，这个就留给读者自己去实现了。
```bash
› cat ~/.ssh/config
# ......
Host ai
HostName 192.168.5.100
Port 22
Host aquamarine
HostName 192.168.5.101
Port 22
Host ruby
HostName 192.168.5.102
Port 22
Host kana
HostName 192.168.5.103
Port 22
```
这样我们就可以使用主机别名进行部署了：
```bash
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --verbose
```
### 4. 使用 Makefile 简化命令
> 注意: Makefile 的 target 名称不能与当前目录下的文件或者目录重名，否则 target 将不会被执行！
在使用 NixOS 的过程中，我们会经常使用 `nixos-rebuild` 命令，经常需要输入一大堆参数，比较繁琐。
所以我使用 Makefile 来管理我的 flake 配置相关的命令，简化使用。
我的 Makefile 大概内容截取如下：
```makefile
############################################################################
#
# Nix commands related to the local machine
#
############################################################################
deploy:
nixos-rebuild switch --flake . --use-remote-sudo
debug:
nixos-rebuild switch --flake . --use-remote-sudo --show-trace --verbose
update:
nix flake update
history:
nix profile history --profile /nix/var/nix/profiles/system
gc:
# remove all generations older than 7 days
sudo nix profile wipe-history --profile /nix/var/nix/profiles/system --older-than 7d
# garbage collect all unused nix store entries
sudo nix store gc --debug
############################################################################
#
# Idols, Commands related to my remote distributed building cluster
#
############################################################################
add-idols-ssh-key:
ssh-add ~/.ssh/ai-idols
aqua: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo
aqua-debug: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --show-trace --verbose
ruby: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo
ruby-debug: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo --show-trace --verbose
kana: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo
kana-debug: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo --show-trace --verbose
idols: aqua ruby kana
idols-debug: aqua-debug ruby-debug kana-debug
```
将上述 Makefile 放到 NixOS 配置的根目录下，然后我们就可以使用 `make` 命令来执行相关的命令了。
比如说我这里 `make deploy` 就是部署 NixOS 配置到本地主机，`make idols` 就是部署到我的远程主机集群。

5
docs/zh/best-practices/intro.md Normal file
View File

@ -0,0 +1,5 @@
## 最佳实践 {#best-practices}
Nix 非常强大且灵活，做一件事有非常多的方法，这就导致了很难找到最合适的方法来做你的工作。
这里记录了一些我在使用 NixOS 中学习到的最佳实践，希望能帮到你。

62
docs/zh/best-practices/remote-deployment.md Normal file
View File

@ -0,0 +1,62 @@
## 远程部署
社区的一些工具，比如 [NixOps](https://github.com/NixOS/nixops), [deploy-rs](https://github.com/serokell/deploy-rs), 跟 [colmena](https://github.com/zhaofengli/colmena)，都可以用来部署 NixOS 配置到远程主机，但是都太复杂了，所以先全部跳过。
实际上我们前面使用了多次的 NixOS 本机部署命令 `nixos-rebuild`，这个工具也支持通过 ssh 协议进行远程部署，非常方便。
美中不足的是，`nixos-rebuild` 不支持使用密码认证进行部署，所以要想使用它进行远程部署，我们需要：
1. 为远程主机配置 ssh 公钥认证。
2. 为了避免 sudo 密码认证失败，需要使用 `root` 用户进行部署，或者给用户授予 sudo 权限不需要密码认证。
1. 相关 issue: <https://github.com/NixOS/nixpkgs/issues/118655>
在搞定上面两点后，我们就可以使用 `nixos-rebuild` 进行远程部署了：
```bash
# 1. 首先将本地的 ssh 私钥加载到 ssh-agent 中，以便后续使用
ssh-add ~/.ssh/ai-idols
# 2. 将 NixOS 配置部署到远程主机，使用第一步添加的 ssh key 进行认证，用户名默认为 `$USER`
nixos-rebuild --flake .#aquamarine --target-host 192.168.4.1 --build-host 192.168.4.1 switch --use-remote-sudo --verbose
```
上面的命令会将 NixOS 配置部署到 `aquamarine` 这台主机上，参数解释如下：
1. `--target-host`: 设置远程主机的 ip 地址
2. `--build-host` 指定了构建 NixOS 配置的主机，这里设置为跟 `--target-host` 相同，表示在远程主机上构建配置。
3. `--use-remote-sudo` 表示部署需要用到远程主机的 sudo 权限，如果不设置这个参数，部署会失败。
如果你希望在本地构建配置，然后再部署到远程主机，可以命令中的 `--build-host aquamarinr` 替换为 `--build-host localhost`。
另外如果你不想直接使用 ip 地址，可以在 `~/.ssh/config` 或者 `/etc/ssh/ssh_config` 中定义一些主机别名，比如：
> 当然如下这份配置也完全可以通过 Nix 来管理，这个就留给读者自己去实现了。
```bash
› cat ~/.ssh/config
# ......
Host ai
HostName 192.168.5.100
Port 22
Host aquamarine
HostName 192.168.5.101
Port 22
Host ruby
HostName 192.168.5.102
Port 22
Host kana
HostName 192.168.5.103
Port 22
```
这样我们就可以使用主机别名进行部署了：
```bash
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --verbose
```

56
docs/zh/best-practices/run-downloaded-binaries-on-nixos.md Normal file
View File

@ -0,0 +1,56 @@
## 运行非 NixOS 的二进制文件 {#run-non-nixos-binaries}
NixOS 不遵循 FHS 标准，因此你从网上下载的二进制程序在 NixOS 上大概率是跑不了的。
为了在 NixOS 上跑这些非 NixOS 的二进制程序，需要做一些骚操作。有位老兄在这里总结了 10 种实现此目的的方法：[Different methods to run a non-nixos executable on Nixos](https://unix.stackexchange.com/questions/522822/different-methods-to-run-a-non-nixos-executable-on-nixos)，推荐一读。
我个人用的比较多的方法是，直接创建一个 FHS 环境来运行二进制程序，这种方法非常方便易用。
大概玩法是这样的，首先在你的 `environment.systemPackages` 中添加这个包：
```nix
{ config, pkgs, lib, ... }:
{
# ......
environment.systemPackages = with pkgs; [
# ......o
# create a fhs environment by command `fhs`, so we can run non-nixos packages in nixos!
(pkgs.buildFHSUserEnv (base // {
name = "fhs";
targetPkgs = pkgs: (
# pkgs.buildFHSUserEnv 只提供一个最小的 FHS 环境，缺少很多常用软件所必须的基础包
# 所以直接使用它很可能会报错
#
# pkgs.appimageTools 提供了大多数程序常用的基础包，所以我们可以直接用它来补充
(pkgs.appimageTools.defaultFhsEnvArgs.targetPkgs pkgs) ++ with pkgs; [
pkg-config
ncurses
# 如果你的 FHS 程序还有其他依赖，把它们添加在这里
]
);
profile = "export FHS=1";
runScript = "bash";
extraOutputsToInstall = ["dev"];
}))
];
# ......
}
```
部署好上面的配置后，你就能用 `fhs` 命令进入我们定义好的 FHS 环境了，然后就可以运行你下载的二进制程序了，比如：
```shell
# 进入我们定义好的 fhs 环境，它就跟其他 Linux 发行版一样了
$ fhs
# 看看我们的 /usr/bin 里是不是多了很多东西
(fhs) $ ls /usr/bin
# 尝试下跑一个非 nixos 的二进制程序
(fhs) $ ./bin/code
```
## 参考
- [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse]: Just as the title says, it is a collection of tips and tricks for NixOS desktop.

71
docs/zh/best-practices/simplify-nixos-related-commands.md Normal file
View File

@ -0,0 +1,71 @@
## 使用 Makefile 简化命令
> 注意: Makefile 的 target 名称不能与当前目录下的文件或者目录重名，否则 target 将不会被执行！
在使用 NixOS 的过程中，我们会经常使用 `nixos-rebuild` 命令，经常需要输入一大堆参数，比较繁琐。
所以我使用 Makefile 来管理我的 flake 配置相关的命令，简化使用。
我的 Makefile 大概内容截取如下：
```makefile
############################################################################
#
# Nix commands related to the local machine
#
############################################################################
deploy:
nixos-rebuild switch --flake . --use-remote-sudo
debug:
nixos-rebuild switch --flake . --use-remote-sudo --show-trace --verbose
update:
nix flake update
history:
nix profile history --profile /nix/var/nix/profiles/system
gc:
# remove all generations older than 7 days
sudo nix profile wipe-history --profile /nix/var/nix/profiles/system --older-than 7d
# garbage collect all unused nix store entries
sudo nix store gc --debug
############################################################################
#
# Idols, Commands related to my remote distributed building cluster
#
############################################################################
add-idols-ssh-key:
ssh-add ~/.ssh/ai-idols
aqua: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo
aqua-debug: add-idols-ssh-key
nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --show-trace --verbose
ruby: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo
ruby-debug: add-idols-ssh-key
nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo --show-trace --verbose
kana: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo
kana-debug: add-idols-ssh-key
nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo --show-trace --verbose
idols: aqua ruby kana
idols-debug: aqua-debug ruby-debug kana-debug
```
将上述 Makefile 放到 NixOS 配置的根目录下，然后我们就可以使用 `make` 命令来执行相关的命令了。
比如说我这里 `make deploy` 就是部署 NixOS 配置到本地主机，`make idols` 就是部署到我的远程主机集群。

151
docs/zh/flakes/index.md
View File

@ -1,151 +0,0 @@
## 七、Nix Flakes 的使用 {#nix-flakes-usage}
到这里我们已经写了不少 Nix Flakes 配置来管理 NixOS 系统了，这里再简单介绍下 Nix Flakes 更细节的内容，以及常用的 nix flake 命令。
### 1. Flake 的 inputs {#flake-inputs}
`flake.nix` 中的 `inputs` 是一个 attribute set，用来指定当前 Flake 的依赖，inputs 有很多种类型，举例如下：
```nix
{
inputs = {
# 以 GitHub 仓库为数据源，指定使用 master 分支，这是最常见的 input 格式
nixpkgs.url = "github:Mic92/nixpkgs/master";
# Git URL，可用于任何基于 https/ssh 协议的 Git 仓库
git-example.url = "git+https://git.somehost.tld/user/path?ref=branch&rev=fdc8ef970de2b4634e1b3dca296e1ed918459a9e";
# 上面的例子会复制 .git 到本地, 如果数据量较大，建议使用 shallow=1 参数避免复制 .git
git-directory-example.url = "git+file:/path/to/repo?shallow=1";
# 本地文件夹 (如果使用绝对路径，可省略掉前缀 'path:')
directory-example.url = "path:/path/to/repo";
# 如果数据源不是一个 flake，则需要设置 flake=false
bar = {
url = "github:foo/bar/branch";
flake = false;
};
sops-nix = {
url = "github:Mic92/sops-nix";
# `follows` 是 inputs 中的继承语法
# 这里使 sops-nix 的 `inputs.nixpkgs` 与当前 flake 的 inputs.nixpkgs 保持一致，
# 避免依赖的 nixpkgs 版本不一致导致问题
inputs.nixpkgs.follows = "nixpkgs";
};
# 将 flake 锁定在某个 commit 上
nix-doom-emacs = {
url = "github:vlaci/nix-doom-emacs?rev=238b18d7b2c8239f676358634bfb32693d3706f3";
flake = false;
};
# 使用 `dir` 参数指定某个子目录
nixpkgs.url = "github:foo/bar?dir=shu";
}
}
```
### 2. Flake 的 outputs {#flake-outputs}
`flake.nix` 中的 `outputs` 是一个 attribute set，是整个 Flake 的构建结果，每个 Flake 都可以有许多不同的 outputs。
一些特定名称的 outputs 有特殊用途，会被某些 Nix 命令识别处理，比如：
- Nix packages: 名称为 `apps.<system>.<name>`, `packages.<system>.<name>` 或 `legacyPackages.<system>.<name>` 的 outputs，都是 Nix 包，通常都是一个个应用程序。
- 可以通过 `nix build .#name` 来构建某个 nix 包
- Nix Helper Functions: 名称为 `lib` 的 outputs 是 Flake 函数库，可以被其他 Flake 作为 inputs 导入使用。
- Nix development environments: 名称为 `devShells` 的 outputs 是 Nix 开发环境
- 可以通过 `nix develop` 命令来使用该 Output 创建开发环境
- NixOS configurations: 名称为 `nixosConfigurations.<hostname>` 的 outputs，是 NixOS 的系统配置。
- `nixos-rebuild switch .#<hostname>` 可以使用该 Output 来部署 NixOS 系统
- Nix templates: 名称为 `templates` 的 outputs 是 flake 模板
- 可以通过执行命令 `nix flake init --template <reference>` 使用模板初始化一个 Flake 包
- 其他用户自定义的 outputs，可能被其他 Nix 相关的工具使用
NixOS Wiki 中给出的使用案例：
```nix
{ self, ... }@inputs:
{
# Executed by `nix flake check`
checks."<system>"."<name>" = derivation;
# Executed by `nix build .#<name>`
packages."<system>"."<name>" = derivation;
# Executed by `nix build .`
packages."<system>".default = derivation;
# Executed by `nix run .#<name>`
apps."<system>"."<name>" = {
type = "app";
program = "<store-path>";
};
# Executed by `nix run . -- <args?>`
apps."<system>".default = { type = "app"; program = "..."; };
# Formatter (alejandra, nixfmt or nixpkgs-fmt)
formatter."<system>" = derivation;
# Used for nixpkgs packages, also accessible via `nix build .#<name>`
legacyPackages."<system>"."<name>" = derivation;
# Overlay, consumed by other flakes
overlays."<name>" = final: prev: { };
# Default overlay
overlays.default = {};
# Nixos module, consumed by other flakes
nixosModules."<name>" = { config }: { options = {}; config = {}; };
# Default module
nixosModules.default = {};
# Used with `nixos-rebuild --flake .#<hostname>`
# nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
nixosConfigurations."<hostname>" = {};
# Used by `nix develop .#<name>`
devShells."<system>"."<name>" = derivation;
# Used by `nix develop`
devShells."<system>".default = derivation;
# Hydra build jobs
hydraJobs."<attr>"."<system>" = derivation;
# Used by `nix flake init -t <flake>#<name>`
templates."<name>" = {
path = "<store-path>";
description = "template description goes here?";
};
# Used by `nix flake init -t <flake>`
templates.default = { path = "<store-path>"; description = ""; };
}
```
### 3. Flake 命令行的使用 {#flake-commands-usage}
在启用了 `nix-command` & `flakes` 功能后，我们就可以使用 Nix 提供的新一代 Nix 命令行工具 [New Nix Commands][New Nix Commands] 了，下面列举下其中常用命令的用法：
```bash
# 解释下这条指令涉及的参数：
# `nixpkgs#ponysay` 意思是 `nixpkgs` 这个 flake 中的 `ponysay` 包。
# `nixpkgs` 是一个 flakeregistry ida,
# nix 会从 <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json> 中
# 找到这个 id 对应的 github 仓库地址
# 所以这个命令的意思是创建一个新环境，安装并运行 `nixpkgs` 这个 flake 提供的 `ponysay` 包。
# 注：前面已经介绍过了，nix 包 是 flake outputs 中的一种。
echo "Hello Nix" | nix run "nixpkgs#ponysay"
# 这条命令和上面的命令作用是一样的，只是使用了完整的 flake URI，而不是 flakeregistry id。
echo "Hello Nix" | nix run "github:NixOS/nixpkgs/nixos-unstable#ponysay"
# 这条命令的作用是使用 zero-to-nix 这个 flake 中名 `devShells.example` 的 outptus 来创建一个开发环境，
# 然后在这个环境中打开一个 bash shell。
nix develop "github:DeterminateSystems/zero-to-nix#example"
# 除了使用远程 flake uri 之外，你也可以使用当前目录下的 flake 来创建一个开发环境。
mkdir my-flake && cd my-flake
## 通过模板初始化一个 flake
nix flake init --template "github:DeterminateSystems/zero-to-nix#javascript-dev"
## 使用当前目录下的 flake 创建一个开发环境，并打开一个 bash shell
nix develop
# 或者如果你的 flake 有多个 devShell 输出，你可以指定使用名为 example 的那个
nix develop .#example
# 构建 `nixpkgs` flake 中的 `bat` 这个包
# 并在当前目录下创建一个名为 `result` 的符号链接，链接到该构建结果文件夹。
mkdir build-nix-package && cd build-nix-package
nix build "nixpkgs#bat"
# 构建一个本地 flake 和 nix develop 是一样的，不再赘述
```
此外 [Zero to Nix - Determinate Systems][Zero to Nix - Determinate Systems] 是一份全新的 Nix & Flake 新手入门文档，写得比较浅显易懂，适合新手用来入门。

41
docs/zh/flakes/inputs.md Normal file
View File

@ -0,0 +1,41 @@
### 1. Flake 的 inputs {#flake-inputs}
`flake.nix` 中的 `inputs` 是一个 attribute set，用来指定当前 Flake 的依赖，inputs 有很多种类型，举例如下：
```nix
{
inputs = {
# 以 GitHub 仓库为数据源，指定使用 master 分支，这是最常见的 input 格式
nixpkgs.url = "github:Mic92/nixpkgs/master";
# Git URL，可用于任何基于 https/ssh 协议的 Git 仓库
git-example.url = "git+https://git.somehost.tld/user/path?ref=branch&rev=fdc8ef970de2b4634e1b3dca296e1ed918459a9e";
# 上面的例子会复制 .git 到本地, 如果数据量较大，建议使用 shallow=1 参数避免复制 .git
git-directory-example.url = "git+file:/path/to/repo?shallow=1";
# 本地文件夹 (如果使用绝对路径，可省略掉前缀 'path:')
directory-example.url = "path:/path/to/repo";
# 如果数据源不是一个 flake，则需要设置 flake=false
bar = {
url = "github:foo/bar/branch";
flake = false;
};
sops-nix = {
url = "github:Mic92/sops-nix";
# `follows` 是 inputs 中的继承语法
# 这里使 sops-nix 的 `inputs.nixpkgs` 与当前 flake 的 inputs.nixpkgs 保持一致，
# 避免依赖的 nixpkgs 版本不一致导致问题
inputs.nixpkgs.follows = "nixpkgs";
};
# 将 flake 锁定在某个 commit 上
nix-doom-emacs = {
url = "github:vlaci/nix-doom-emacs?rev=238b18d7b2c8239f676358634bfb32693d3706f3";
flake = false;
};
# 使用 `dir` 参数指定某个子目录
nixpkgs.url = "github:foo/bar?dir=shu";
}
}
```

6
docs/zh/flakes/intro.md Normal file
View File

@ -0,0 +1,6 @@
## 七、Nix Flakes 的使用 {#nix-flakes-usage}
到这里我们已经写了不少 Nix Flakes 配置来管理 NixOS 系统了，这里再简单介绍下 Nix Flakes 更细节的内容，以及常用的 nix flake 命令。
此外 [Zero to Nix - Determinate Systems][Zero to Nix - Determinate Systems] 是一份全新的 Nix & Flake 新手入门文档，写得比较浅显易懂，也可以一读。

68
docs/zh/flakes/outputs.md Normal file
View File

@ -0,0 +1,68 @@
### 2. Flake 的 outputs {#flake-outputs}
`flake.nix` 中的 `outputs` 是一个 attribute set，是整个 Flake 的构建结果，每个 Flake 都可以有许多不同的 outputs。
一些特定名称的 outputs 有特殊用途，会被某些 Nix 命令识别处理，比如：
- Nix packages: 名称为 `apps.<system>.<name>`, `packages.<system>.<name>` 或 `legacyPackages.<system>.<name>` 的 outputs，都是 Nix 包，通常都是一个个应用程序。
- 可以通过 `nix build .#name` 来构建某个 nix 包
- Nix Helper Functions: 名称为 `lib` 的 outputs 是 Flake 函数库，可以被其他 Flake 作为 inputs 导入使用。
- Nix development environments: 名称为 `devShells` 的 outputs 是 Nix 开发环境
- 可以通过 `nix develop` 命令来使用该 Output 创建开发环境
- NixOS configurations: 名称为 `nixosConfigurations.<hostname>` 的 outputs，是 NixOS 的系统配置。
- `nixos-rebuild switch .#<hostname>` 可以使用该 Output 来部署 NixOS 系统
- Nix templates: 名称为 `templates` 的 outputs 是 flake 模板
- 可以通过执行命令 `nix flake init --template <reference>` 使用模板初始化一个 Flake 包
- 其他用户自定义的 outputs，可能被其他 Nix 相关的工具使用
NixOS Wiki 中给出的使用案例：
```nix
{ self, ... }@inputs:
{
# Executed by `nix flake check`
checks."<system>"."<name>" = derivation;
# Executed by `nix build .#<name>`
packages."<system>"."<name>" = derivation;
# Executed by `nix build .`
packages."<system>".default = derivation;
# Executed by `nix run .#<name>`
apps."<system>"."<name>" = {
type = "app";
program = "<store-path>";
};
# Executed by `nix run . -- <args?>`
apps."<system>".default = { type = "app"; program = "..."; };
# Formatter (alejandra, nixfmt or nixpkgs-fmt)
formatter."<system>" = derivation;
# Used for nixpkgs packages, also accessible via `nix build .#<name>`
legacyPackages."<system>"."<name>" = derivation;
# Overlay, consumed by other flakes
overlays."<name>" = final: prev: { };
# Default overlay
overlays.default = {};
# Nixos module, consumed by other flakes
nixosModules."<name>" = { config }: { options = {}; config = {}; };
# Default module
nixosModules.default = {};
# Used with `nixos-rebuild --flake .#<hostname>`
# nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
nixosConfigurations."<hostname>" = {};
# Used by `nix develop .#<name>`
devShells."<system>"."<name>" = derivation;
# Used by `nix develop`
devShells."<system>".default = derivation;
# Hydra build jobs
hydraJobs."<attr>"."<system>" = derivation;
# Used by `nix flake init -t <flake>#<name>`
templates."<name>" = {
path = "<store-path>";
description = "template description goes here?";
};
# Used by `nix flake init -t <flake>`
templates.default = { path = "<store-path>"; description = ""; };
}
```

37
docs/zh/flakes/the-new-cli.md Normal file
View File

@ -0,0 +1,37 @@
### 3. Flake 命令行的使用 {#flake-commands-usage}
在启用了 `nix-command` & `flakes` 功能后，我们就可以使用 Nix 提供的新一代 Nix 命令行工具 [New Nix Commands][New Nix Commands] 了，下面列举下其中常用命令的用法：
```bash
# 解释下这条指令涉及的参数：
# `nixpkgs#ponysay` 意思是 `nixpkgs` 这个 flake 中的 `ponysay` 包。
# `nixpkgs` 是一个 flakeregistry ida,
# nix 会从 <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json> 中
# 找到这个 id 对应的 github 仓库地址
# 所以这个命令的意思是创建一个新环境，安装并运行 `nixpkgs` 这个 flake 提供的 `ponysay` 包。
# 注：前面已经介绍过了，nix 包 是 flake outputs 中的一种。
echo "Hello Nix" | nix run "nixpkgs#ponysay"
# 这条命令和上面的命令作用是一样的，只是使用了完整的 flake URI，而不是 flakeregistry id。
echo "Hello Nix" | nix run "github:NixOS/nixpkgs/nixos-unstable#ponysay"
# 这条命令的作用是使用 zero-to-nix 这个 flake 中名 `devShells.example` 的 outptus 来创建一个开发环境，
# 然后在这个环境中打开一个 bash shell。
nix develop "github:DeterminateSystems/zero-to-nix#example"
# 除了使用远程 flake uri 之外，你也可以使用当前目录下的 flake 来创建一个开发环境。
mkdir my-flake && cd my-flake
## 通过模板初始化一个 flake
nix flake init --template "github:DeterminateSystems/zero-to-nix#javascript-dev"
## 使用当前目录下的 flake 创建一个开发环境，并打开一个 bash shell
nix develop
# 或者如果你的 flake 有多个 devShell 输出，你可以指定使用名为 example 的那个
nix develop .#example
# 构建 `nixpkgs` flake 中的 `bat` 这个包
# 并在当前目录下创建一个名为 `result` 的符号链接，链接到该构建结果文件夹。
mkdir build-nix-package && cd build-nix-package
nix build "nixpkgs#bat"
# 构建一个本地 flake 和 nix develop 是一样的，不再赘述
```