pyrox.dev
+1
.github/CODEOWNERS
+1
.github/CODEOWNERS
+1
doc/doc-support/default.nix
+1
doc/doc-support/default.nix
···
+5
-1
doc/doc-support/lib-function-docs.nix
+5
-1
doc/doc-support/lib-function-docs.nix
···
+9
-7
doc/doc-support/lib-function-locations.nix
+9
-7
doc/doc-support/lib-function-locations.nix
···
+2
-1
lib/default.nix
+2
-1
lib/default.nix
······
+196
lib/path/README.md
+196
lib/path/README.md
···+The purpose of this library is to process [filesystem paths]. It does not read files from the filesystem.+As an extension of the path value type, it inherits the same intended use cases and limitations:+- A path implicitly imports the referenced files into the Nix store when interpolated to a string. Therefore paths are not suitable to access files at build- or run-time, as you risk importing the path from the evaluation system instead.+- Absolute paths are represented with the Nix [path value type]. Nix automatically normalises these paths.+- Subpaths are represented with the [string value type] since path value types don't support relative paths. This library normalises these paths as safely as possible. Absolute paths in strings are not supported.+It is a stricter form of a relative path, notably [without support for `..` components][parents] since those could escape the base directory.+This library is designed to be as safe and intuitive as possible, throwing errors when operations are attempted that would produce surprising results, and giving the expected result otherwise.+This library is designed to work well as a dependency for the `lib.filesystem` and `lib.sources` library components. Contrary to these library components, `lib.path` does not read any paths from the filesystem.+- `dirOf path` returns the path to the parent directory of `path`, unless `path` is the filesystem root, in which case `path` is returned.+- There can be multiple filesystem roots: `p == dirOf p` and `q == dirOf q` does not imply `p == q`.+- While there's only a single filesystem root in stable Nix, the [lazy trees feature](https://github.com/NixOS/nix/pull/6530) introduces [additional filesystem roots](https://github.com/NixOS/nix/pull/6530#discussion_r1041442173).+- `path1 == path2` returns `true` only if `path1` points to the same filesystem path as `path2`.+Notably we do not make the assumption that we can turn paths into strings using `toString path`.+Each subsection here contains a decision along with arguments and counter-arguments for (+) and against (-) that decision.+Observing: Since subpaths are a form of relative paths, they can have a leading `./` to indicate it being a relative path, this is generally not necessary for tools though.+- (+) In shells, just running `foo` as a command wouldn't execute the file `foo`, whereas `./foo` would execute the file. In contrast, `foo/bar` does execute that file without the need for `./`. This can lead to confusion about when a `./` needs to be prefixed. If a `./` is always included, this becomes a non-issue. This effectively then means that paths don't overlap with command names.+- (+) Using paths in command line arguments could give problems if not escaped properly, e.g. if a path was `--version`. This is not a problem with `./--version`. This effectively then means that paths don't overlap with GNU-style command line options.+- (-) `./` is not required to resolve relative paths, resolution always has an implicit `./` as prefix.+- (-) But only if you give it an argument of `.`. If you give it the argument `some-directory`, it won't prefix that.+Observing: The subpath that produces the base directory can be represented with `.` or `./` or `./.`.+- (+) `./` would be inconsistent with [the decision to not persist trailing slashes][trailing-slashes].+- (+) `.` can be interpreted as a shell command (it's a builtin for sourcing files in `bash` and `zsh`).+- (+) `.` would be the only path without a `/`. It could not be used as a Nix path expression, since those require at least one `/` to be parsed as such.+As inputs all three variants are supported for subpaths (and we can't do anything about absolute paths)+- (+) `./.` is a valid Nix path expression, although this property does not hold for every relative path or subpath.+Considering: Paths should be as safe to use as possible. We should generate string outputs in the library and not encourage users to do that themselves.+- (+) It's simpler for the users of the library. One doesn't have to convert a path a string before it can be used.+- (+) Naively converting the list representation to a string with `concatStringsSep "/"` would break for `[]`, requiring library users to be more careful.+- (+) It doesn't encourage people to do their own path processing and instead use the library.+With a list representation it would seem easy to just use `lib.lists.init` to get the parent directory, but then it breaks for `.`, which would be represented as `[ ]`.+Decision: `..` path components in string paths are not supported, neither as inputs nor as outputs. Hence, string paths are called subpaths, rather than relative paths.+- (+) If we wanted relative paths to behave according to the "physical" interpretation (as a directory tree with relations between nodes), it would require resolving symlinks, since e.g. `foo/..` would not be the same as `.` if `foo` is a symlink.+- (-) The "logical" interpretation is also valid (treating paths as a sequence of names), and is used by some software. It is simpler, and not using symlinks at all is safer.+- (-) We could just not handle such cases, e.g. `equals "foo" "foo/bar/.. == false`. The paths are different, we don't need to check whether the paths point to the same thing.+- (+) Assume we said `relativeTo /foo /bar == "../bar"`. If this is used like `/bar/../foo` in the end, and `bar` turns out to be a symlink to somewhere else, this won't be accurate.+- (-) We could decide to not support such ambiguous operations, or mark them as such, e.g. the normal `relativeTo` will error on such a case, but there could be `extendedRelativeTo` supporting that.+- (+) If we can convincingly argue that all such use cases are better done e.g. with runtime tools, the library not supporting it can nudge people towards using those.+- (+) Then we'd have to throw an error for doing `append /some/path "../foo"`, making it non-composable.+- (+) The same is for returning paths with `..`: `relativeTo /foo /bar => "../bar"` would produce a non-composable path.+- (+) We argue that `..` is not needed at the Nix evaluation level, since we'd always start evaluation from the project root and don't go up from there.+- (+) If you need `..` for building or runtime, you can use build-/run-time tooling to create those (e.g. `realpath` with `--relative-to`), or use absolute paths instead.+Observing: Subpaths can contain trailing slashes, like `foo/`, indicating that the path points to a directory and not a file.+Considering: Paths should be as consistent as possible, there should only be a single normalisation for the same path.+- (+) It allows normalisations to be unique, in that there's only a single normalisation for the same path. If trailing slashes were preserved, both `foo/bar` and `foo/bar/` would be valid but different normalisations for the same path.+- (+) Nix itself doesn't support trailing slashes when parsing and doesn't preserve them when appending paths.+- (-) [Rust's std::path](https://doc.rust-lang.org/std/path/index.html) does preserve them during [construction](https://doc.rust-lang.org/std/path/struct.Path.html#method.new).+- (+) Doesn't preserve them when returning individual [components](https://doc.rust-lang.org/std/path/struct.Path.html#method.components).+- (+) Doesn't preserve them when [canonicalizing](https://doc.rust-lang.org/std/path/struct.Path.html#method.canonicalize).+- (+) [Python 3's pathlib](https://docs.python.org/3/library/pathlib.html#module-pathlib) doesn't preserve them during [construction](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath).+- (-) [Haskell's filepath](https://hackage.haskell.org/package/filepath-1.4.100.0) has [explicit support](https://hackage.haskell.org/package/filepath-1.4.100.0/docs/System-FilePath.html#g:6) for handling trailing slashes.+- (-) Does preserve them for [normalisation](https://hackage.haskell.org/package/filepath-1.4.100.0/docs/System-FilePath.html#v:normalise).+- (-) [NodeJS's Path library](https://nodejs.org/api/path.html) preserves trailing slashes for [normalisation](https://nodejs.org/api/path.html#pathnormalizepath).+- (+) For [parsing a path](https://nodejs.org/api/path.html#pathparsepath) into its significant elements, trailing slashes are not preserved.+- (+) Nix's builtin function `dirOf` gives an unexpected result for paths with trailing slashes: `dirOf "foo/bar/" == "foo/bar"`.+- (-) We are writing a path library to improve handling of paths though, so we shouldn't use these functions and discourage their use.+- (-) Unexpected result when normalising intermediate paths, like `relative.normalise ("foo" + "/") + "bar" == "foobar"`.+- (+) Even with a trailing slash, the path is the same, it's only an indication that it's a directory.
+218
lib/path/default.nix
+218
lib/path/default.nix
···+# Always return relative paths with `./` as a prefix (./path.md#leading-dots-for-relative-paths)+# An empty string is not a valid relative path, so we need to return a `.` when we have no components+- (Uniqueness) There's only a single normalisation for the paths that lead to the same file system node:+"lib.path.subpath.normalise: Argument is not a valid subpath string: ${subpathInvalidReason path}";
+34
lib/path/tests/default.nix
+34
lib/path/tests/default.nix
···
+64
lib/path/tests/generate.awk
+64
lib/path/tests/generate.awk
···
+60
lib/path/tests/prop.nix
+60
lib/path/tests/prop.nix
···+# If not, the resulting value is normalised again and an appropriate attribute set added to the output list.+"For valid subpath \"${str}\", the normalisation \"${tryOnce.value}\" was not a valid subpath";+"For valid subpath \"${str}\", normalising it once gives \"${tryOnce.value}\" but normalising it twice gives a different result: \"${tryTwice.value}\"";+"For valid subpath \"${str}\", appending to an absolute Nix path value gives \"${absConcatOrig}\", but appending the normalised result \"${tryOnce.value}\" gives a different value \"${absConcatNormalised}\"";
+179
lib/path/tests/prop.sh
+179
lib/path/tests/prop.sh
···+die "For invalid subpath \"$str\", lib.path.subpath.normalise returned this result: \"$normalised\""+echo >&2 "Checking idempotency of each result and making sure the realpath result isn't changed"+die "realpath of the original string \"$str\" (\"$real_orig\") is not the same as realpath of the normalisation \"$result\" (\"$real_norm\")"+echo >&2 "$(bc <<< "scale=1; 100 / $count * $invalid")% of the total $count generated strings were invalid subpath strings, and were therefore ignored"+die "Normalisations \"$norm_p\" and \"$norm_q\" are different, but the realpath of them is the same: \"$real_p\""
+125
lib/path/tests/unit.nix
+125
lib/path/tests/unit.nix
···
+3
lib/tests/release.nix
+3
lib/tests/release.nix
+9
-1
pkgs/tools/nix/nixdoc/default.nix
+9
-1
pkgs/tools/nix/nixdoc/default.nix
······+url = "https://github.com/nix-community/nixdoc/pull/27/commits/ea542735bf675fe2ccd37edaffb9138d1a8c1b7e.patch";