nixpkgs-fmt - Nixpkgs 代码格式化工具

状态：beta

本项目的目标是格式化 nixpkgs 中的 nix 代码，以提高代码的一致性。理想情况下，通过预提交钩子和后续的 ofborg 强制执行格式。

演示

您可以在浏览器中尝试 nixpkgs-fmt。页面还提供了提交代码样本的方式，如果您觉得输出不满意：https://nix-community.github.io/nixpkgs-fmt/

设计决策

您可能会问自己；为什么还需要另一个 nix 代码格式化工具？

nixpkgs-fmt 的主要目标是提供一些提交到 nixpkgs（我们的主要软件仓库）的 nix 代码的整体一致性。

在此阶段，理解这一点非常重要：代码格式化工具可能有多种输出。这些输出将取决于多种冲突的愿望，并且根据对每个要求的重视程度，输出将发生变化。

对于 nixpkgs-fmt，我们有以下几个：

1. 最小化合并冲突。nixpkgs 在许多拉取请求中都很常见，我们希望避免它们不必要地过时。
2. 仅展开，不折叠。开发者可以选择一个元素是放在单行还是多行。
3. 尊重开发者的表达性。空行可以作为分隔代码块的方式很有用。
4. 每行仅更改一个 (+/-) 的缩进。不清楚为什么，但似乎是个好主意。

推论规则

• 由于（1），格式与 nixpkgs 中已有的格式非常接近。
• 由于（1）。不要垂直对齐值，单行更改可能会引入一个非常大的差异。
• 由于（1）。避免过多的规则。更多的规则意味着更多的格式更改，这会导致合并冲突。
• 由于（2）。不要强制执行行长度。行长度限制也会创建复杂的启发式方法。

在我们开始这个项目的时候，其他格式化工具都没有这样权重。

要实现这一点，我们需要一个保留空白和注释的解析器，rnix为我们提供了这个解析器。然后创建一个遵循AST并使用重写规则修补树的引擎。这个设计的优点是它也可以处理不完整或损坏的nix代码。我们能够格式化到缺少/损坏的部分，这使得它非常适合潜在的编辑器集成。

大多数其他格式化工具都采用了一种非常打印的方法，即解析AST，然后非常打印器检查并格式化AST回代码，而不考虑空白和新行。优点是它最初更容易实现。输出非常严格，相同的AST总是会给出相同的输出。一个缺点是，非常打印器需要处理Nix代码的所有可能的组合，以使它们看起来很好。

使用nixpkgs-fmt，输出将取决于代码最初是如何格式化的。开发者仍然可以对其代码的格式化方式有所影响。如果没有规则适用于复杂的情况，代码将被保留。对于nixpkgs，这种方法将是首选的，因为它最小化了差异。

恭喜您读到这里，我希望这能稍微澄清为什么nixpkgs-fmt存在以及它可以扮演什么角色。

用法

nixpkgs-fmt 1.2.0
Format Nix code

USAGE:
    nixpkgs-fmt [FLAGS] [OPTIONS] [FILE]...

FLAGS:
        --check      Only test if the formatter would produce differences
        --explain    Show which rules are violated
    -h, --help       Prints help information
        --parse      Show syntax tree instead of reformatting
    -V, --version    Prints version information

OPTIONS:
        --output-format <FORMAT>    Set output format of --parse [default: rnix]  [possible values: rnix, json]

ARGS:
    <FILE>...    File to reformat in place. If no file is passed, read from stdin.

树遍历

当nixpkgs-fmt被给定为文件参数的文件夹时，它将使用与ripgrep相同的ignore crate遍历该文件夹，使用8个并行线程。

默认情况下，它将自动忽略读取.ignore、.gitignore和.git/info/exclude文件的文件，按此顺序。如果需要忽略其他文件，也可以在调用中添加--exclude <glob>。

安装

nixpkgs-fmt在nixpkgs master中可用。nix-env --fmt。

也可以直接从该存储库安装它

nix-env-f https://github.com/nix-community/nixpkgs-fmt/archive/master.tar.gz -iA nixpkgs-fmt

VSCode扩展

有几个VSCode扩展可以使使用nixpkgs-fmt变得方便。查看

• B4dM4n.nixpkgs-fmt
• jnoortheen.nix-ide

pre-commit钩子

该项目也可以作为pre-commit钩子安装。

将其添加到项目的.pre-commit-config.yaml中

-   repo: https://github.com/nix-community/nixpkgs-fmt
    rev: master
    hooks:
    -   id: nixpkgs-fmt

请确保环境中已有rust。

然后运行pre-commit install-hooks

开发

安装Rust和Cargo或运行nix-shell以加载项目依赖项。

安装pre-commit并运行pre-commit install以在存储库上设置git钩子。这将允许随着时间的推移保持代码格式良好。

然后使用cargo run来构建和运行软件。

运行Fuzzer

$ cargo install cargo-fuzz
$ mkdir -p ./fuzz/corpus/fmt
$ cp test_data/**.nix ./fuzz/corpus/fmt
$ rustup run nightly -- cargo fuzz run fmt

或者使用nix

$ nix-shell --run "cargo fuzz run fmt"

• fmt是./fuzz/Cargo.toml中目标的名字

Fuzzer将无限运行或直到找到崩溃为止。崩溃的输入将被写入到fuzz/artifacts目录。提交这个crash-文件，它将被自动通过单元测试进行测试。

文档

• 如何编写新规则
• 如何使用WASM
• 我们的发布方式

相关项目

欢迎提交您的项目！

使用nixpkgs-fmt

• Emacs集成，包括格式化保存的次要模式
• rnix-lsp - Nix的Lambda服务器

格式化工具

• alejandra - 另一个基于rnix的格式化工具，使用基于规则的引擎。
• canonix - 使用tree-sitter-nix语法的Haskell编写的Nix格式化原型。
• format-nix - 使用tree-sitter-nix的nix格式化工具。
• nix-format - 基于Emacs的Nix格式化工具。
• nix-lsp - 使用rnix的Nix语言服务器。
• nixfmt - 使用Haskell编写的nix格式化工具。

代码检查工具

• nix-linter

解析器

• hnix - 包含解析器的Nix的Haskell实现。解析器不保留注释。
• rnix - 基于rowan的Rust Nix解析器
• tree-sitter-nix - Tree Sitter是一个宽容的解析器，被Atom用于即时语法高亮和其他用途。这是Nix的实现。

讨论

• nixpkgs风格指南
• 关于Nix表达式格式化
• [工作]实现一个nix-fmt格式化工具

赞助商

这项工作得到了NumTide的支持。