From d99c1edfcc8ccbeb323e2f7841fe165c54a3beed Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sun, 13 Aug 2023 13:16:35 +0800 Subject: [PATCH] feat: custom NIX_PATH and Flake registry --- docs/.vitepress/config.ts | 8 ++++ .../nix-path-and-flake-registry.md | 41 ++++++++++++++++++ .../nix-path-and-flake-registry.md | 43 +++++++++++++++++++ 3 files changed, 92 insertions(+) create mode 100644 docs/best-practices/nix-path-and-flake-registry.md create mode 100644 docs/zh/best-practices/nix-path-and-flake-registry.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index e2329f5..45d5c65 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -159,6 +159,10 @@ function themeConfigEnglish() { text: "Simplify NixOS-related Commands", link: "/best-practices/simplify-nixos-related-commands.md", }, + { + text: "Custom NIX_PATH and Flake Registry", + link: "/best-practices/nix-path-and-flake-registry.md", + }, { text: "Remote Deployment", link: "/best-practices/remote-deployment.md", @@ -341,6 +345,10 @@ function themeConfigChinese() { text: "使用 Makefile 简化常用命令", link: "/zh/best-practices/simplify-nixos-related-commands.md", }, + { + text: "自定义 NIX_PATH 与 Flake Registry", + link: "/zh/best-practices/nix-path-and-flake-registry.md", + }, { text: "远程部署 Nix 配置", link: "/zh/best-practices/remote-deployment.md", diff --git a/docs/best-practices/nix-path-and-flake-registry.md b/docs/best-practices/nix-path-and-flake-registry.md new file mode 100644 index 0000000..f45d6bd --- /dev/null +++ b/docs/best-practices/nix-path-and-flake-registry.md @@ -0,0 +1,41 @@ +# Custom NIX_PATH and Flake Registry {#custom-nix-path-and-flake-registry} + +## Introduction to NIX_PATH {#nix-path-introduction} + +The Nix search path is controlled by the environment variable `NIX_PATH`, which follows the same format as the Linux `PATH` environment variable, consisting of multiple paths separated by colons. + +Paths in Nix expressions that look like `` are resolved using the path named `name` from the `NIX_PATH`. + +This usage pattern is no longer recommended under the Flakes feature because it results in Flake builds depending on a mutable environment variable `NIX_PATH`, compromising reproducibility. + +However, in certain scenarios, we still need to use `NIX_PATH`, such as when we frequently use the command `nix repl ''`, which utilizes the Nixpkgs found through `NIX_PATH` search. + +## Introduction to Flakes Registry {#flakes-registry-introduction} + +The Flakes Registry is a center for Flake registration that assists us in using shorter IDs instead of lengthy flake repository addresses when using commands like `nix run`, `nix shell`, and more. + +By default, Nix looks up the corresponding GitHub repository address for this ID from . + +For instance, if we execute `nix run nixpkgs#ponysay hello`, Nix will automatically retrieve the GitHub repository address for `nixpkgs` from the aforementioned JSON file. It then downloads the repository, locates the `flake.nix` within, and runs the corresponding `ponysay` package. + +## Custom NIX_PATH and Flake Registry {#custom-nix-path-and-flake-registry} + +The roles of `NIX_PATH` and the Flake Registry have been explained earlier. +In daily use, we typically want the `nixpkgs` used in commands like `nix repl ''`, `nix run nixpkgs#ponysay hello` to match the system's `nixpkgs`. This requires us to customize the `NIX_PATH` and Flake Registry. + +In your NixOS configuration, adding the following module will achieve the mentioned requirements: + +```nix +{ + # Make `nix run nixpkgs#nixpkgs` use the same nixpkgs as the one used by this flake. + nix.registry.nixpkgs.flake = nixpkgs; + + # Make `nix repl ''` use the same nixpkgs as the one used by this flake. + environment.etc."nix/inputs/nixpkgs".source = "${nixpkgs}"; + nix.nixPath = ["/etc/nix/inputs"]; +} +``` + +## References + +- [Chapter 15. Nix Search Paths - Nix Pills](https://nixos.org/guides/nix-pills/nix-search-paths.html) diff --git a/docs/zh/best-practices/nix-path-and-flake-registry.md b/docs/zh/best-practices/nix-path-and-flake-registry.md new file mode 100644 index 0000000..363225e --- /dev/null +++ b/docs/zh/best-practices/nix-path-and-flake-registry.md @@ -0,0 +1,43 @@ +# 自定义 NIX_PATH 与 Flake Registry {#custom-nix-path-and-flake-registry} + +## NIX_PATH 介绍 {#nix-path-introduction} + +Nix 搜索路径由环境变量 `NIX_PATH` 控制，它的格式与 Linux 的 `PATH` 环境变量一致，由冒号分隔的多个路径组成。 + +Nix 表达式中形如 `` 的路径会被解析为 `NIX_PATH` 中名为 `name` 的路径。 + +这种使用方式在 Flakes 特性下已经不推荐使用了，因为它会导致 Flake 的构建结果依赖一个可变的环境变量 `NIX_PATH`，可复现能力大打折扣。 + +但是在某些场景下，我们还是需要使用 `NIX_PATH`，比如我们前面多次使用了 `nix repl ''` 命令，它就是使用了从 `NIX_PATH` 搜索到的 Nixpkgs。 + +## Flakes Registry 介绍 {#flakes-registry-introduction} + +Flake Registry 是一个 Flake 注册中心，它可以帮助我们在使用 `nix run`, `nix shell` 等命令时，使用一个简短的 id 来代替长长的 flake 仓库地址。 + +默认情况下，Nix 会从 中找到这个 id 对应的 github 仓库地址。 + +比如说我们执行 `nix run nixpkgs#ponysay hello`，nix 会自动从上述 json 文件中找到 `nixpkgs` 对应的 github 仓库地址，然后下载这个仓库，再通过其中的 `flake.nix` 查找对应的 `ponysay` 包并运行它。 + + +## 自定义 NIX_PATH 与 Flake Registry {#custom-nix-path-and-flake-registry} + +前面说明了 `NIX_PATH` 与 Flake Registry 的作用。 +在日常使用中，我们一般都会希望能在执行 `nix repl ''`, `nix run nixpkgs#ponysay hello` 等命令时，使用的 nixpkgs 与系统一致，这就需要我们自定义 `NIX_PATH` 与 Flake Registry。 + +在你的 NixOS 配置中，添加如下 module 即可实现上述需求： + +```nix +{ + # make `nix run nixpkgs#nixpkgs` use the same nixpkgs as the one used by this flake. + nix.registry.nixpkgs.flake = nixpkgs; + + # make `nix repl ''` use the same nixpkgs as the one used by this flake. + environment.etc."nix/inputs/nixpkgs".source = "${nixpkgs}"; + nix.nixPath = ["/etc/nix/inputs"]; +} +``` + +## 参考 + +- [Chapter 15. Nix Search Paths - Nix Pills](https://nixos.org/guides/nix-pills/nix-search-paths.html) +