fix: hint users to enable Developer Mode on Windows symlink extraction failure

[pb01ka]

Problem

Refer - #940 (comment)

When rattler-build tries to extract a source archive (e.g. a .tar.gz) that contains symbolic links on Windows without Developer Mode enabled, the extraction fails with an error such as (with no hint or actionable information):

 ╭─ Running build for recipe: podman-desktop-1.26.2-hf0b5a29_0
 │
 │ ╭─ Fetching source code
 │ │ Fetching source from url: https://github.com/podman-desktop/podman-desktop/archive/refs/tags/v1.26.2.tar.gz
 │ │ Downloading from: https://github.com/podman-desktop/podman-desktop/archive/refs/tags/v1.26.2.tar.gz
 │ │ ⚠ warning Failed to fetch from https://github.com/podman-desktop/podman-desktop/archive/refs/tags/v1.26.2.tar.gz: Failed to extract archive: Failed to extract tar
 │ │ ⚠ warning .gz: failed to unpack `\\?\C:\Users\Gagan\staged-recipes\build_artifacts\src_cache\.tmpyweool\podman-desktop-1.26.2\CLAUDE.md`
 │ │
 │ ╰─────────────────── (took 8 seconds)
 │
 ╰─────────────────── (took 8 seconds)
Error:   x Failed to extract archive: Failed to extract tar.gz: failed to unpack `\\?\C:\Users\Gagan\staged-recipes\build_artifacts\src_cache\.tmpyweool\podman-desktop-
  | 1.26.2\CLAUDE.md`

Solution

This PR detects the failure scenario and surfaces an actionable hint:

1. Registry check - a new is_windows_developer_mode_enabled() function checks whether Developer Mode is enabled by reading the registry key HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock → AllowDevelopmentWithoutDevLicense using the winreg crate. This is safe Rust with no unsafe blocks.

2. Improved error message - a new tar_unpack_error() helper wraps every tar .unpack() failure. On Windows, when Developer Mode is detected as disabled, the error is extended with a clear hint:

   hint: Extracting this archive failed on Windows. The archive may contain symbolic
   links, which require Developer Mode or administrator privileges to create.
   Please enable Developer Mode in:
   Developer settings > Developer Mode, then retry the build.
   

3. Test coverage - a Windows-only unit test (test_symlink_extraction_error_message) builds a minimal .tar.gz containing a symlink entry and asserts that:

   • with Developer Mode off: the error message contains "Developer Mode".
   • with Developer Mode on: extraction succeeds without error.

Notes

• No behaviour change on Linux/macOS — tar_unpack_error compiles to a simple CacheError::ExtractionError wrapper on non-Windows targets.
• The winreg crate is added as a new Windows-only dependency; it provides safe, idiomatic Rust access to the Windows registry with no unsafe code.

---

This is my first contribution to rattler-build. I've done my best to follow the project's conventions, but I'm very much looking forward to feedback and suggestions for improvement - please feel free to point out anything that could be done better!

[baszalmstra]

I assume this is also a specific io error that we are looking for? Permission denied or something?

[pb01ka]

Not reliably. The error code when symlink creation fails on Windows with Developer Mode disabled is not consistent. ERROR_PRIVILEGE_NOT_HELD (1314) is the most common (as per my observation), but it can't reliably help in identifying a "symlink failed" error from the error alone, we instead gate the hint on the Developer Mode registry check: if Developer Mode is off and tar extraction fails for any reason, we surface the hint. The hint copy uses "may contain symbolic links" to reflect this uncertainty.

[baszalmstra]

Having a clear error is nice, but maybe even just continuing would be even nicer.

In rattler/pixi we try to unpack symlinks, and if they fail, we simply ignore them and issue a warning. I think that behavior would also be fine here. If it's a problem that they are missing, you will find out soon enough during the build itself.

Another option that we could pursue instead is to create a symlink, and if that fails, we simply materialize/create a copy of the file.

[pb01ka]

@baszalmstra I think both alternatives are better UX than a hard failure.

1. Warn and skip

In rattler/pixi we try to unpack symlinks, and if they fail, we simply ignore them and issue a warning. I think that behavior would also be fine here. If it's a problem that they are missing, you will find out soon enough during the build itself.

It is simpler to implement - the tar crate surfaces individual entry errors, so we could iterate entries manually instead of calling unpack(), and skip symlink entries that fail. The downside is the extracted tree is incomplete, which may cause silent build failures later.

2. Fall back to copying the target file

Another option that we could pursue instead is to create a symlink, and if that fails, we simply materialize/create a copy of the file.

This approach is more robust - if the symlink target exists in the archive, we can materialise it as a regular file. The extracted tree is functionally complete even without actual symlinks.

I'd lean towards the copy fallback since it's transparent to the build, but it does require iterating tar entries manually and tracking regular files as they're extracted so we can copy them when a symlink to them is encountered. Happy to implement whichever approach you prefer.