feat: builtins.readSymlink primop by JustAGuyTryingHisBest · Pull Request #15093 · NixOS/nix

JustAGuyTryingHisBest · 2026-01-26T23:51:57Z

Motivation

#13111 (comment)

Context

This is a stepping stone to - #13111

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

Ericson2314

I like it

(and I was not at the meeting where this was originally idea-approved)

JustAGuyTryingHisBest · 2026-01-27T17:10:54Z

@Ericson2314 - Installer CI failed on an authentication issue unrelated to my change. I don't have the option to rerun. Is that only available to admins?

Ericson2314 · 2026-01-27T17:17:11Z

Done

JustAGuyTryingHisBest · 2026-01-27T17:30:01Z

Done

Rad. Much appreciated!

Ericson2314 · 2026-01-27T18:09:55Z

+static void prim_readSymlink(EvalState & state, const PosIdx pos, Value ** args, Value & v)
+{
+    auto path = state.realisePath(pos, *args[0], SymlinkResolution::Ancestors);
+    v.mkString(path.readLink(), state.mem);


Oh hmm actually this part might need more thinking hmm. I would rather that it be a path.

What about reading symlinks inside trees fetched by fetchTree or similar - those might very well be dangling or relative.

That makes sense! I updated the implementation to return a path.

What about reading symlinks inside trees fetched by fetchTree or similar - those might very well be dangling or relative.

See what I wrote in obsidiansystems@own-location-for-symlink, which @xokdvium and I have talked about before.

The issue, for example, that some source successors, like git repos for flakes for pure eval, shouldn't really support absolute paths at all, because the repo isn't necessary mounted at root or anywhere else. It should only support relative paths.

My suggestion that we should convert the raw target of the symlink into a path is a bit more complex than what you implemented if we take this concern into account, because we need to actually define this per-source-accessor policy of how symlinks should be interpreted / what should be allowed.

Sorry this is spiraling into something more complex than what you started with!

I reread the original issue, and it appears the intended behavior is to match POSIX readlink returning a raw string.
Does it make sense to open a new ticket to differentiate this from the original ticket and POSIX realpath behavior?

#13111 (comment)

Noticed one thing that I want to think about more

xokdvium · 2026-01-26T23:54:04Z

@@ -0,0 +1 @@
+error: filesystem error: read_symlink: not a symlink ["/pwd/lang/readDir/bar"]


Oh, this error really needs to be wrapped in the accessor IMO

Is the suggestion here to catch the error in the primop and throw NotASymlink("file '%s' is not a symbolic link", showPath(path)); or add a cleaner error message in PosixSourceAccessor::readLink().

To be clear, @xokdivium is just noticing a preexisting issue with PosixSourceAcccesor, it is not the fault of this PR.

xokdvium · 2026-01-27T18:55:39Z

+static void prim_readSymlink(EvalState & state, const PosIdx pos, Value ** args, Value & v)
+{
+    auto path = state.realisePath(pos, *args[0], SymlinkResolution::Ancestors);
+    v.mkString(path.readLink(), state.mem);


What about reading symlinks inside trees fetched by fetchTree or similar - those might very well be dangling or relative.

edolstra

Maybe this should be called builtins.readLink since that's more consistent with the readlink() POSIX function, the readlink GNU command, and readLink() in our own interfaces. It's unambiguous since you can't read hard links.

edolstra · 2026-02-02T17:11:21Z

+    const auto path = state.realisePath(pos, *args[0], SymlinkResolution::Ancestors);
+    const auto target = path.readLink();
+    const auto parent = path.parent();
+    v.mkPath(SourcePath(path.accessor, CanonPath(target, parent.path)), state.mem);


It's a bit questionable whether this should return a path value or just the raw symlink as a string (without canonicalisation). If the former, maybe this function should be called builtins.canonPath or builtins.resolvePath or whatever (and accept non-symlink paths as well).

roberth · 2026-02-06T22:05:56Z

Maybe this should be called builtins.readLink

Counterpoints:

Explicit is good
Internal consistency:
- FSO in the manual uses "symbolic link"
- ```
nix-repl> builtins.readFileType /etc/static
"symlink"
```
- NAR uses symlink

roberth · 2026-02-06T22:16:31Z

We have previously put some wisdom in the manual

An arbitrary string, known as the target of the symlink.

In general, Nix does not assign any semantics to symbolic links. Certain operations however, may make additional assumptions and attempt to use the target to find another file system object.

While I am a fan of path values, I haven't heard a compelling reason why we should diverge from this definition.
I am not sure that "symlink resolution is useful" counts, and implementing path resolution is another can of worms where we have very little room for error, risking eval repro when we inevitably find that we got some corner case wrong.
That kind of complexity is better implemented in Nixpkgs lib where iterating does not risk eval reproducibility.

I had opened that can of worms for the build-path path component security checking, but that solution was not chosen. Is this instance of the problem different? I would argue yes, but for the worse.

(I should still have that work somewhere if you insist)

Ericson2314 · 2026-02-10T16:11:13Z

The short answer is that I am worried that the nixpkgs lib will implement something that should stop working when our symlink dereferencing gets better, and that will cause problems / break expectations,

For example in some context absolute path symlinks should be followed, and in other contexts they should not be.

JustAGuyTryingHisBest · 2026-02-21T21:53:17Z

@Ericson2314 @roberth @edolstra - Is the consensus here to change the name to readLink, return a raw string, and defer on path resolution/canonicalisation?

feat: builtins.readSymlink primop

f5d63dd

JustAGuyTryingHisBest requested a review from edolstra as a code owner January 26, 2026 23:51

github-actions Bot added the with-tests Issues related to testing. PRs with tests have some priority label Jan 26, 2026

Ericson2314 previously approved these changes Jan 27, 2026

View reviewed changes

JustAGuyTryingHisBest added 2 commits January 26, 2026 22:29

fix quotes

048edd4

Merge remote-tracking branch 'upstream/master' into read-symlink-primop

69ba166

JustAGuyTryingHisBest force-pushed the read-symlink-primop branch from 99e4af7 to 69ba166 Compare January 27, 2026 06:52

Ericson2314 requested a review from xokdvium January 27, 2026 17:47

Ericson2314 reviewed Jan 27, 2026

View reviewed changes

builtins.readSymlink return Path

cd0537e

xokdvium reviewed Jan 27, 2026

View reviewed changes

edolstra reviewed Feb 2, 2026

View reviewed changes

tomberek requested a review from edolstra March 20, 2026 15:30

		@@ -0,0 +1 @@
		error: filesystem error: read_symlink: not a symlink ["/pwd/lang/readDir/bar"]

Uh oh!

Conversation

JustAGuyTryingHisBest commented Jan 26, 2026 • edited by Ericson2314 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Context

Uh oh!

Ericson2314 left a comment

Choose a reason for hiding this comment

Uh oh!

JustAGuyTryingHisBest commented Jan 27, 2026

Uh oh!

Ericson2314 commented Jan 27, 2026

Uh oh!

JustAGuyTryingHisBest commented Jan 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ericson2314 Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edolstra left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roberth commented Feb 6, 2026

Uh oh!

roberth commented Feb 6, 2026

Uh oh!

Ericson2314 commented Feb 10, 2026

Uh oh!

JustAGuyTryingHisBest commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

JustAGuyTryingHisBest commented Jan 26, 2026 •

edited by Ericson2314

Loading

Ericson2314 Jan 28, 2026 •

edited

Loading

edolstra left a comment •

edited

Loading