[Feature Idea] Clang virtual filesystem support for case-sensitive, symlink-free operation

[humbletim]

Hi! I've been using xwin as part of edge-compiling a legacy C++ project and ran into challenges with symlinks on a case-sensitive filesystem.

I explored an alternative approach that avoids symlinks entirely -- having xwin generate a vfsoverlay.json file for use with Clang's -ivfsoverlay option.

The Feature (from my prototype):

This change adds a new command-line flag, --vfsoverlay, to the xwin splat command. When this flag is used, xwin will not create any filesystem symlinks. Instead, it will generate a vfsoverlay.json file in the root of the splat output directory. This file contains all the file path mappings that would have been created as symlinks.

This feature is critical for using xwin in non-linux environments where creating symlinks is not possible or desired, such as on standard Windows installations on a case-sensitive filesystem (without administrator rights or Developer Mode enabled).

Proof-of-Concept:

I have a working prototype of this feature in my dev-fork:

• feat: Implement --vfsoverlay flag for symlink-free operation humbletim/xwin#1

I've verified that it solves my immediate need. The patch history includes the initial implementation (largely AI-assisted by google-labs-jules[bot], as seen in the commits) as well as several manual fix-ups and refinements from my own testing.

Next Steps (No Obligation):

I'm opening this as an issue for discussion rather than a direct PR. I'm not yet an avid Rust developer or in a position to champion this through to a production-ready feature.

However, I wanted to share this R&D in case the idea is useful to you or others. If it aligns with the project's goals, feel free to use any part of the proof-of-concept as a starting point.

Thanks for maintaining xwin!

[Jake-Shadle]

I wasn't aware of the vfsoverlay feature, it does look like a good thing to support. My question is if it actually works, including linking, as https://reviews.llvm.org/D124411 seems to indicate LLD does not support it yet? If vfsoverlay only works with the compiler it is not much use.

[humbletim]

That's a great question. You're right to check—that D124411 review was for ELF, but it directly led to this follow-up patch that specifically added the feature to lld-link for Windows/COFF:

• [D125800: [COFF] Add vfsoverlay flag](https://reviews.llvm.org/D125800) (committed as fd9962e75d89 back in July 2022).

I can confirm it definitely works for both compiling and linking. I'm successfully using it with Clang 19 and lld-link on both Ubuntu and Windows. The prototype PR has my exact build commands and a test .cpp that requires overlay support to successfully compile and link on a case-sensitive filesystem.

A couple of small nuances I found during testing:

1. lld-link only seems to accept one /vfsoverlay:filename.json argument (it doesn't accumulate them like clang's -ivfsoverlay option).
2. To keep the splat folder relocatable, I opted for relative paths in the vfsoverlay.json (using overlay-relative: true). This required a workaround: I had to pass both the relative and full paths to the linker's search path (via -L ) for lld-link to resolve sdk-internal libs correctly. (Using absolute paths avoids this, but then the prepared splat folder can't be moved).

Let me know if you have any other questions!

[mon]

AI writing style notwithstanding, I do actually find this a useful feature - I managed to find a project (YY-Thunks, which does horrible linking crimes to get new software working on Windows XP) that manages to have over 15 misses on the current symlink cohort.

I actually didn't test the overlay feature in clang at all because I also saw that first link saying LLD didn't support it, but if this is a viable thing to merge I can go build this branch and test whether it works as described.