Windows platform notes

[mitchcapper]

Initial README.md for Windows. Mostly written for a different planned docs PR. Not sure if you want to somehow link to this from the main README.

[bioball]

Thanks! Did you mean to have this committed to our repo? Not sure if that's the right place to put it.

Should be good enough to add these notes to #20.

[mitchcapper]

Yes my thought was to add a readme for Windows users. I am guessing Windows will not be a primary target platform for Pkl for some time. That means there may be various levels of work-arounds required for Windows users. Platform specific notes/readmes are not uncommonly found in repos/docs.

I would say the best place would probably be right in the documentation itself on pkl-lang.org. Section added to installation and likely a second page talking about Windows specific issues for users trying to use that platform. That might be more official than Pkl wants to go at this point.

I think a windows readme file in the repo is the second more appropriate place. General users of Pkl won't be as likely to see it, but somewhat more advanced users would. Linking to it from the main readme would help visibility, but even just in the repo itself would likely suffice.

The final option would be an issue, as in #20. These notes could be added there but issues are not exactly the best place for user documentation. For one notes that are targeting end users (like these) would get mixed in with notes about the bugs themselves and fixing them rather than say all noted at the top. That makes it a good bit harder for users to parse, understand what is relevant to them, and to follow updates.

I posted a comment including some of the issues and potential solutions in that ticket but it was mostly developer targeted. It included a reference to a system level API which is irrelevant as well to someone just looking to using it. Lets say one of those items gets fixed, IE file:///MyPath being translated to include the drive letter (which for security purposes it should anyway). When that happens is the hope I go back to edit my comment if it is serving also as user documentation? Someone else might post another comment below mentioning the partial fix to that issue but now end users have to keep track not just on the original problems but then which of those are fixed and how by reading all the comments with their deltas to understand the current requirements for the platform.

An issue also requires the user to think of filing a bug or checking existing bugs. When you look at the releases or documentation however it would largely just seem anti-windows support. When you look at releases: https://github.com/apple/pkl/releases all of the release specific assets are only for non-windows platforms (no universal jar files). The https://pkl-lang.org/main/current/pkl-cli/index.html#installation mentions a java executable, and says known to work on macOS and Oracle Linux). A smart enough user may assume that might work on windows and there is a download command provided there for users but it won't work on windows out of the box (as uses curl which most users won't have and removes the .jar extension). Again a smart user can figure it out, but I doubt most users would look for release file locations in the docs and not in the release. If a user doesn't even see something looking like it might work on Windows they may just assume that platform doesn't work on Windows and not even look to issues.

Discussions maybe slightly better than issues? But still requires some users to maintain a primary post with the current solutions/problems for it to be best.

This is why I went the readme route, something that can be officially maintained as end user documentation to what platform specific items exist for Windows and how to work around them. As things change updating it is simple and keeps the current solutions well known. All without being part of the official documentation, so as to lend to having official platform support. One can easily add a glairing warning to the top that README that Windows is not an officially supported platform and any bugs/issues are handled at best on a best-effort approach when specific to that platform.

This all started when I was putting together: apple/pkl-jvm-examples#9 and originally duplicating some of the Windows specific notes there (as high likelihood users would encounter them). That didn't seem appropriate as they were far from specific to just the codegen module. I could point to #20 instead if going with the issue is the desired direction.

You are Apple, but Windows is a primary platform for a large portion of developers. Having some level of documentation on what is required or what they can expect would seem to be one of the better ways to increase adoption of a new language.

At the end of the day whatever direction you go works for me as I just try to contribute back whatever issues/work arounds/fixes I find to be able to use projects for myself.

[bioball]

Thanks for your comments.

Windows is an important platform, and we are aiming to provide Windows support in our next release (June).
For now, the best workaround is probably to use WSL, which I believe is working fine for folks.

You're right that we're missing any notes about Windows anywhere in our docs. I'd be happy to accept a PR to our website that details the lack of Windows support to our installation page.