feat: one more section about flake's 'self' (#131)

ryan4yin · Mar 22, 2024 · cb4941e · cb4941e
1 parent ca15ac1
commit cb4941e
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 5 deletions.
diff --git a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md b/docs/nixos-with-flakes/nixos-with-flakes-enabled.md
@@ -183,8 +183,6 @@ results of the flake:
     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 {
@@ -230,7 +228,28 @@ example:
 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}
+### 3. The Special Parameter `self` of the `outputs` Function {#special-parameter-self-of-outputs-function}
+
+Although we have not mentioned it before, all the example code in the previous sections
+has one more special parameter in the `outputs` function, and we will briefly introduce
+its purpose here.
+
+The description of it in the [nix flake - Nix Manual] is:
+
+> The special input named `self` refers to the outputs and source tree of this flake.
+
+This means that `self` is the return value of the current flake's `outputs` function and
+also the path to the current flake's source code folder (source tree).
+
+We are not using the `self` parameter here, but in some more complex examples (or
+configurations you may find online) later, you will see the usage of `self`.
+
+> Note: You might come across some code where people use `self.outputs` to reference the
+> outputs of the current flake, which is indeed possible. However, the Nix Manual does not
+> provide any explanation for this, and it is considered an internal implementation detail
+> of flakes. It is not recommended to use this in your own code!
+
+### 4. 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.**
 
@@ -545,6 +564,8 @@ referenced for future mention:
   versions of Nixpkgs are introduced as dependencies, allowing for flexible selection of
   packages from various versions of Nixpkgs.
 
+[nix flake - Nix Manual]:
+  https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake#flake-inputs
 [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

diff --git a/docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md b/docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md
@@ -162,7 +162,6 @@ attribute set，这个返回的 attribute set 即为该 flake 的构建结果：
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
   };
 
-  # 这里的 `self` 是个特殊参数，它指向 `outputs` 函数返回的 attribute set 自身，即自引用
   outputs = { self, nixpkgs, ... }@inputs: {
     # hostname 为 my-nixos 的主机会使用这个配置
     nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
@@ -202,7 +201,26 @@ sudo nixos-rebuild switch --flake /path/to/your/flake#your-hostname
 sudo nixos-rebuild switch --flake github:owner/repo#your-hostname
 ```
 
-### 3. `nixpkgs.lib.nixosSystem` 函数的简单介绍 {#simple-introduction-to-nixpkgs-lib-nixos-system}
+### 3. `outputs` 函数的特殊参数 `self` {#special-parameter-self-of-outputs-function}
+
+虽然我们前面并未提到，但是前面的所有示例代码中，`outputs` 函数都还有一个特殊的参数
+`self`，这里我们简单介绍一下它的作用。
+
+[nix flake - Nix Manual] 对其的描述是：
+
+> The special input named `self` refers to the outputs and source tree of this flake.
+
+所以说 `self` 是当前 flake 的 `outputs` 函数的返回值，同时也是当前 flake 源码的文件夹路径
+（source tree）。
+
+这里我们并未使用到 `self` 这个参数，在后面一些更复杂的例子（或者你网上搜
+到的一些配置）中，我们会看到 `self` 的用法。
+
+> 注意：你可能会在一些代码中看到，有人会使用 `self.outputs` 来引用当前 flake 的输出，这
+> 确实是可行的，但 Nix Manual 并未对其做任何说明，属于是 flake 的内部实现细节，不建议在
+> 你自己的代码中使用！
+
+### 4. `nixpkgs.lib.nixosSystem` 函数的简单介绍 {#simple-introduction-to-nixpkgs-lib-nixos-system}
 
 **一个 Flake 可以依赖其他 Flakes，从而使用它们提供的功能**。
 
@@ -492,6 +510,8 @@ nix run github:helix-editor/helix/master
 - [Downgrading or Upgrading Packages](./downgrade-or-upgrade-packages.md): 这里引入了不同
   版本的 Nixpkgs 作为依赖项，从而能很灵活地选用不同版本的 Nixpkgs 中的包。
 
+[nix flake - Nix Manual]:
+  https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake#flake-inputs
 [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