about summary refs log tree commit diff
path: root/nixpkgs/pkgs/test/nixpkgs-check-by-name/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'nixpkgs/pkgs/test/nixpkgs-check-by-name/README.md')
-rw-r--r--nixpkgs/pkgs/test/nixpkgs-check-by-name/README.md102
1 files changed, 0 insertions, 102 deletions
diff --git a/nixpkgs/pkgs/test/nixpkgs-check-by-name/README.md b/nixpkgs/pkgs/test/nixpkgs-check-by-name/README.md
deleted file mode 100644
index 1aa256978416..000000000000
--- a/nixpkgs/pkgs/test/nixpkgs-check-by-name/README.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Nixpkgs pkgs/by-name checker
-
-This directory implements a program to check the [validity](#validity-checks) of the `pkgs/by-name` Nixpkgs directory.
-This is part of the implementation of [RFC 140](https://github.com/NixOS/rfcs/pull/140).
-
-A [pinned version](./scripts/pinned-tool.json) of this tool is used by [this GitHub Actions workflow](../../../.github/workflows/check-by-name.yml).
-See [./scripts](./scripts/README.md#update-pinned-toolsh) for how to update the pinned version.
-
-The source of the tool being right inside Nixpkgs allows any Nixpkgs committer to make updates to it.
-
-## Interface
-
-The interface of the tool is shown with `--help`:
-```
-cargo run -- --help
-```
-
-The interface may be changed over time only if the CI workflow making use of it is adjusted to deal with the change appropriately.
-
-## Validity checks
-
-These checks are performed by this tool:
-
-### File structure checks
-- `pkgs/by-name` must only contain subdirectories of the form `${shard}/${name}`, called _package directories_.
-- The `name`'s of package directories must be unique when lowercased.
-- `name` is a string only consisting of the ASCII characters `a-z`, `A-Z`, `0-9`, `-` or `_`.
-- `shard` is the lowercased first two letters of `name`, expressed in Nix: `shard = toLower (substring 0 2 name)`.
-- Each package directory must contain a `package.nix` file and may contain arbitrary other files.
-
-### Nix parser checks
-- Each package directory must not refer to files outside itself using symlinks or Nix path expressions.
-
-### Nix evaluation checks
-
-Evaluate Nixpkgs with `system` set to `x86_64-linux` and check that:
-- For each package directory, the `pkgs.${name}` attribute must be defined as `callPackage pkgs/by-name/${shard}/${name}/package.nix args` for some `args`.
-- For each package directory, `pkgs.lib.isDerivation pkgs.${name}` must be `true`.
-
-### Ratchet checks
-
-Furthermore, this tool implements certain [ratchet](https://qntm.org/ratchet) checks.
-This allows gradually phasing out deprecated patterns without breaking the base branch or having to migrate it all at once.
-It works by not allowing new instances of the pattern to be introduced, but allowing already existing instances.
-The existing instances are coming from `<BASE_NIXPKGS>`, which is then checked against `<NIXPKGS>` for new instances.
-Ratchets should be removed eventually once the pattern is not used anymore.
-
-The current ratchets are:
-
-- New manual definitions of `pkgs.${name}` (e.g. in `pkgs/top-level/all-packages.nix`) with `args = { }`
-  (see [nix evaluation checks](#nix-evaluation-checks)) must not be introduced.
-- New top-level packages defined using `pkgs.callPackage` must be defined with a package directory.
-  - Once a top-level package uses `pkgs/by-name`, it also can't be moved back out of it.
-
-## Development
-
-Enter the development environment in this directory either automatically with `direnv` or with
-```
-nix-shell
-```
-
-Then use `cargo`:
-```
-cargo build
-cargo test
-cargo fmt
-cargo clippy
-```
-
-## Tests
-
-Tests are declared in [`./tests`](./tests) as subdirectories imitating Nixpkgs with these files:
-- `default.nix`:
-  Always contains
-  ```nix
-  import <test-nixpkgs> { root = ./.; }
-  ```
-  which makes
-  ```
-  nix-instantiate <subdir> --eval -A <attr> --arg overlays <overlays>
-  ```
-  work very similarly to the real Nixpkgs, just enough for the program to be able to test it.
-- `pkgs/by-name`:
-  The `pkgs/by-name` directory to check.
-
-- `all-packages.nix` (optional):
-  Contains an overlay of the form
-  ```nix
-  self: super: {
-    # ...
-  }
-  ```
-  allowing the simulation of package overrides to the real [`pkgs/top-level/all-packages.nix`](../../top-level/all-packages.nix`).
-  The default is an empty overlay.
-
-- `base` (optional):
-  Contains another subdirectory imitating Nixpkgs with potentially any of the above structures.
-  This is used for [ratchet checks](#ratchet-checks).
-
-- `expected` (optional):
-  A file containing the expected standard output.
-  The default is expecting an empty standard output.