search

cubing / cubing.js

🛠 A library for displaying and working with twisty puzzles. Also currently home to the code for Twizzle.
https://js.cubing.net/cubing/
GNU General Public License v3.0
232 stars 42 forks source link

Windows Compatibility for Dev Installation #132

Open dunkOnIT opened 2 years ago

dunkOnIT commented 2 years ago

Trying to install the dev environment on Windows 10 leads to the identification of some compatibility issues between the MacOS/Linux-based design and implementing on Windows.

A windows install was successful, although it required deviating from the README instructions by modifying code and running other terminal (CMD) commands. Thanks to @rokicki for their help in this regard.

Specifically:

I would be interested in working on this issue to the degree my assistance is useful, but would expect that there is a more elegant solution to compatibility than writing different sets of commands for different systems, which is what I would be tempted to attempt :D

For testing purposes I am happy to test any changes.

lgarron commented 2 years ago

Would you mind sharing the state of the code after you've fixed it up to work for Windows?

In general, I would almost certainly prefer requiring something like bash to be used e.g. using WSL, and consider Windows compat to be significantly more maintenance compat than is worth it. I'm also really anticipating the general availability of https://github.com/features/codespaces so that we can recommend that for anyone who is having issues with a local install.

But I'd certainly be willing to consider it it if 1) I'm not personally on the hook for Windows compat maintenance, and 2) we have a GitHub Action in CI that thoroughly tests Windows compatibility for enough of the dev experience.

rokicki commented 2 years ago

Sometimes Lucas and I don't agree. I think making this code work out of the box for Windows, in a simple CMD environment, has great value, and I think the node ecosystem works hard to be platform agnostic and we should too.

So, for instance, using fs.unlink(filename) can be preferred to command("rm filename").

Of course not everything is that simple, but I think writing platform-specific code in a project that is 99.9% platform agnostic violates basic hygiene.

I don't think we are in violent disagreement; I just think that a clean Windows out-of-the-box build has great value.

On Fri, Aug 27, 2021 at 5:00 PM Lucas Garron @.***> wrote:

Would you mind sharing the state of the code after you've fixed it up to work for Windows?

In general, I would almost certainly prefer requiring something like bash to be used e.g. using WSL, and consider Windows compat to be significantly more maintenance compat than is worth it. I'm also really anticipating the general availability of https://github.com/features/codespaces so that we can recommend that for anyone who is having issues with a local install.

But I'd certainly be willing to consider it it if 1) I'm not personally on the hook for Windows compat maintenance, and 2) we have a GitHub Action in CI that thoroughly tests Windows compatibility for enough of the dev experience.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/cubing/cubing.js/issues/132#issuecomment-907530736, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAMOLS33A27VZSTOCFWUEGDT7ARIBANCNFSM5C47ZSOQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

--

lgarron commented 2 years ago

Sometimes Lucas and I don't agree. I think making this code work out of the box for Windows, in a simple CMD environment, has great value, and I think the node ecosystem works hard to be platform agnostic and we should too.

Just to be clear, I'm totally fine with disagreeing on this!

I also agree that it would be better to be platform-agnostic in principle — it's the details of the JS ecosystem (and node in particular) that make me most concerned about maintaining compat.

dunkOnIT commented 2 years ago

Basic question alert: When talking about Windows compatibility, we're talking about dev usage of cubing.js, right? Usage as a library is unaffected (as someone would just run "npm install cubing.js" and move on with their lives)?

In that case, I would argue this should be guided by a values question: How accessible do you want development of cubing.js to be? Given that a majority of developers use Windows, some solution is clearly needed. The question is on the complexity of that solution.

- If cubing.js contribution should be easily accessible to beginner/novice devs: It should work in CMD out-of-the-box - If cubing.js contribution should be accessible to experienced devs: Emulating bash on Windows using WSL would be sufficient

Having said that, I'm relatively inexperienced but would have been happy to use a WSL-based approach myself. But each additional step will make it more likely that people give up.

Two other guiding questions I have:

lgarron commented 2 years ago

Basic question alert: When talking about Windows compatibility, we're talking about dev usage of cubing.js, right? Usage as a library is unaffected (as someone would just run "npm install cubing.js" and move on with their lives)?

Yep!

If npm install cubing had any issues, I'd definitely consider that an important problem. Our job is to output something that works smoothly for that.

In that case, I would argue this should be guided by a values question: How accessible do you want development of cubing.js to be? Given that a majority of developers use Windows, some solution is clearly needed. The question is on the complexity of that solution.

It would be nice to have some stats on what people can use. I've had a whole bunch of people reach out to me about cubing.js, and a lot of them have a POSIX environment already (although a few certainly only had Windows). This might be worth asking at https://www.facebook.com/groups/906869956398886 at least; I'll set a reminder for that.

- If cubing.js contribution should be easily accessible to beginner/novice devs: It should work in CMD out-of-the-box - If cubing.js contribution should be accessible to experienced devs: Emulating bash on Windows using WSL would be sufficient

I think there are two somewhat orthogonal considerations here:

If WSL installation were as "simple" as installing XCode on macOS, we could tell people "click this thing and wait for a few gigabytes to download" but it wouldn't take a lot of knowledge and run smoothly once it's set up.

Unfortunately, it seems that installing WSL is:

( I get the feeling that the latter exists mainly for debugging, and they really prefer people to have accounts.)

So if a Windows Insiders account that is too onerous (are there age restrictions for this?), it might be worth investing some time in compat.

  • Dev priority. Would the work it takes to create native Windows compatibility detract significantly from other current dev priorities?

For me personally, yes. 😢

  • Ongoing maintenance: Would these be expected to be relatively one-off changes? Or are make scripts changing regularly enough that this would introduce additional headaches in a meaningful number of commits?

I have had to make a lot of changes — not because I like it, but usually because we have to work around other ecosystem issues. :-/ If it's easy to pattern-match existing code when writing new code, it might not be a big headache. But I would definitely rely on CI to tell me what's safe to merge for Windows.

Again, I'm kind of hoping that https://github.com/codespaces rescues us here. You pretty much just have to press a button and wait a few minutes, and then you can run make dev immediately. (And you can either use a web editor with a .dev URL, or open the project in VSCode and use localhost:3333 just like local development.)

(We can actually make it even smoother; I'll go fix that up right now.)

dunkOnIT commented 2 years ago

WSL Usage Report-Back

Feedback after installing WSL using the manual method documented here.

I'm not sure how common the need to play with BIOS settings is, but I'm running an unmodified Ryzen 5 on a B350 - so a pretty standard setup I would expect. And changing the BIOS settings was not easy, and would - I expect - be a barrier that would deter all but the most persistent Windows developers.

On that basis, relying on WSL feels a bridge too far in this respect.

Remaining Options

It seems then that there are 4 options to resolve this:

  1. Refactor code to support Windows natively (headache, but reliable)
  2. Do nothing, hope that Windows makes WSL easier to set up in future updates
  3. Do nothing, get prospective Windows devs to use Codespaces when it is available.

On (3) - even should Codespaces become available, we are still asking 2 important things of a prospective dev:

dunkOnIT commented 2 years ago

EDIT: https://github.com/ehmicky/cross-platform-node-guide is a PHENOMENAL resource, which should hopefully serve as a solid guide. With is and the below-mentioned resources as guides, I'm quite keen to start trying to implement some compatibility changes - probably starting with something simple like converting "rm -rf" commands to their "fs" equivalents.

Busy reading up on cross-platform Node development. Two resources that look helpful:

lgarron commented 2 years ago

Alright, I tried copying our CI job to Windows just to see:

https://github.com/cubing/cubing.js/tree/windows-ci

https://github.com/cubing/cubing.js/runs/3482991778?check_suite_focus=true

It looks like it can make it through make build using the included installs of node/npm and mingw-make. But it's unclear how successful it was.

lgarron commented 1 year ago

It looks like the WSL can now be installed from the Microsoft Store: https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/

Perhaps this is now the lowest-friction approach.

dunkOnIT commented 1 year ago

WSL is definitely the best way to go about this - and would prove an invaluable tool for a budding Windows dev in numerous other contexts as well.