From a5959aa12170fc75cafc9e2416fae9aa67f91e6b Mon Sep 17 00:00:00 2001 From: Jason Yundt Date: Wed, 25 Sep 2024 20:21:33 -0400 Subject: [PATCH] docs: specify that flake.lock files are JSON (#11594) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: specify that flake.lock files are JSON Recently, I decided that I was going to write some code that would parse flake.lock files. I went to the Nix Reference Manual in order to look up information on the format of flake.lock files, and I realized that a key detail was missing from the Nix Reference Manual: it never says that flake.lock files are JSON files. This commit fixes that issue. This commit makes sure to specify that flake.lock files are encoded in UTF-8. Confusingly, there’s multiple different JSON standards. Neither ECMA-404, 2nd Edition [1] nor ISO/IEC 21778:2017 [2] mention UTF-8. RFC 8259 requires UTF-8, but only sometimes [3]. I chose to explicitly specify that flake.lock files are UTF-8 in order to avoid any possible ambiguities from the JSON standards. [1]: [2]: [3]: --- src/nix/flake.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/nix/flake.md b/src/nix/flake.md index d8ee4ac71..2b999431c 100644 --- a/src/nix/flake.md +++ b/src/nix/flake.md @@ -565,8 +565,9 @@ or NixOS modules, which are composed into the top-level flake's Inputs specified in `flake.nix` are typically "unlocked" in the sense that they don't specify an exact revision. To ensure reproducibility, Nix will automatically generate and use a *lock file* called -`flake.lock` in the flake's directory. The lock file contains a graph -structure isomorphic to the graph of dependencies of the root +`flake.lock` in the flake's directory. +The lock file is a UTF-8 JSON file. +It contains a graph structure isomorphic to the graph of dependencies of the root flake. Each node in the graph (except the root node) maps the (usually) unlocked input specifications in `flake.nix` to locked input specifications. Each node also contains some metadata, such as the