Update INSTALL.md - Using Junctions on Windows for Seamless Builds

[hellerim]

Added description of how to build Idris2 on Windows using junctions.

Description

Should this change go in the CHANGELOG?

• If this is a fix, user-facing change, a compiler change, or a new paper
  implementation, I have updated CHANGELOG_NEXT.md (and potentially also
  CONTRIBUTORS.md).

[mattpolzin]

I don't have access to a Windows machine but I can imagine how this additional tip could play out so if no one chimes in to suggest otherwise then this looks like a good addition.

[CodingCellist]

Is it possible to have the version be an environment variable, or even better: extracted from chez --version or similar? Just so we don't risk people mistyping the version, and so we don't have to update this whenever a new Chez version releases : )

[hellerim]

probably we are bound to manual handling. Chez Scheme appears to work through several nested cmd calls. I didn't manage to pipe its output into a file; scheme --version > chezvers.dat leaves the file empty; equally I didn't succeed to capture the output in an environment variable. But even if this worked, the junction to the old version should be removed.

In my opinion trying to fully automate updates is not worth the effort. The mklink command is well documented by Microsoft (including the command's delete option), and there is no magic: A junction is a small file which points to a folder; although the dir command produces a listing, a junction cannot be used by programs to run through the folder entries normally.
My first idea was to modify the ProgramFiles environment variable to include double quotes. It turned out that this does not work. Anyway, to keep risk low, I used a Windows virtual machine. (You can get a legal copy of Windows 11 for about 12 $.) Wouldn't this be a possibility to produce a distributable binary copy of the current version and to include this on the download page? I have no idea how much work this would mean in addition to what I experienced - apart from starting the build, the rest takes a couple of minutes which don't require anyone's presence. Running a test suite could be automated as well.

[hellerim]

Here is a solution: Copy these two lines to the file mkChezLink.cmd:

@rd C:\Chez
@for /f "tokens=1" %%i in ('dir "%ProgramFiles%\Chez*" /B /O-D') do mklink /j C:\Chez "%ProgramFiles%\%%i"

Running it will delete an existing junction and create a new one. If Chez Scheme is not installed it does nothing but display a file not found message. In case there are multiple versions it will use the latest one. If the junction does not exist, it will display an error.
Anyway, C:\Chez must be added to the system path (one-time action).

[hellerim]

In the forcommand, a delimiter needs to be added. Otherwise, folder names are extracted only up to the first space. Hence:

@for /f "tokens=1 delims=:" %%i in ('dir "%ProgramFiles%\Chez*" /B /O-D') do mklink /j C:\Chez "%ProgramFiles%\%%i"

I corrected this in my fork.

[CodingCellist]

Would a simple shortcut file work? I am slightly cautious of asking people to create fancy file-system things, especially for stuff that will probably need updating/removing (new Chez release)...

[CodingCellist]

Thank you for the explanations and for putting this together! : )
LGTM, but I think we'll give it a week or so before merging, just to give people with a Windows machine a chance to try it out and report back any errors : )

[hellerim]

I’m fine with this, thank you. Kind regards, Goetz Von: CodingCellist ***@***.***> Gesendet: Mittwoch, 24. Januar 2024 10:18 An: idris-lang/Idris2 ***@***.***> Cc: hellerim ***@***.***>; Author ***@***.***> Betreff: Re: [idris-lang/Idris2] Update INSTALL.md - Using Junctions on Windows for Seamless Builds (PR #3198) @CodingCellist approved this pull request. Thank you for the explanations and for putting this together! : ) LGTM, but I think we'll give it a week or so before merging, just to give people with a Windows machine a chance to try it out and report back any errors : ) — Reply to this email directly, view it on GitHub <#3198 (review)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG2K5FBQMBYNU3YNMMQXQ3YQDGTXAVCNFSM6AAAAABCD5R5J6VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMYTQNBQHA3DGMRRGA> . You are receiving this because you authored the thread. <https://github.com/notifications/beacon/AAG2K5G2HMXSMVP7QI3UYZLYQDGTXA5CNFSM6AAAAABCD5R5J6WGG33NNVSW45C7OR4XAZNRKB2WY3CSMVYXKZLTORJGK5TJMV32UY3PNVWWK3TUL5UWJTTNXFL6U.gif> Message ID: ***@***.*** ***@***.***> >

[hellerim]

Follow up: I tried another couple of installations and found a few things which did not run smoothly because some minor but important actions don’t happen automatically. I found that it’s quite time-consuming (surprise!) to identify the missing pieces. In the end, I decided to write my findings down in a small workflow description which I moved towards the end of the document, just before the troubleshooting section. Since not everyone interested in learning about Idris can be expected to be technically familiar with a Windows environment, I thought this would be helpful. From my lecturing experiences I know that nowadays many, many people running through a software development education are Windows users whose acquaintance with their systems is low. However, this should not be a hurdle for learning Idris! Kind regards, Goetz Von: CodingCellist ***@***.***> Gesendet: Mittwoch, 24. Januar 2024 10:18 An: idris-lang/Idris2 ***@***.***> Cc: hellerim ***@***.***>; Author ***@***.***> Betreff: Re: [idris-lang/Idris2] Update INSTALL.md - Using Junctions on Windows for Seamless Builds (PR #3198) @CodingCellist approved this pull request. Thank you for the explanations and for putting this together! : ) LGTM, but I think we'll give it a week or so before merging, just to give people with a Windows machine a chance to try it out and report back any errors : ) — Reply to this email directly, view it on GitHub <#3198 (review)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG2K5FBQMBYNU3YNMMQXQ3YQDGTXAVCNFSM6AAAAABCD5R5J6VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMYTQNBQHA3DGMRRGA> . You are receiving this because you authored the thread. <https://github.com/notifications/beacon/AAG2K5G2HMXSMVP7QI3UYZLYQDGTXA5CNFSM6AAAAABCD5R5J6WGG33NNVSW45C7OR4XAZNRKB2WY3CSMVYXKZLTORJGK5TJMV32UY3PNVWWK3TUL5UWJTTNXFL6U.gif> Message ID: ***@***.*** ***@***.***> >

[mattpolzin]

The newest changes to this PR are a bit more of what I would expect to see in a third party resource that walks through installation step by step for a particular target audience. I think we should keep the INSTALL.md file a bit more high level so that it is easy to use as a resource for those already experienced with build tools and easier to maintain.

I don't mean we shouldn't be supportive of all skill levels, but just like we don't go into detail on installing individual prerequisites for Linux I don't think we want to go into details of installing MSYS or Mingw; I imagine there are resources elsewhere online that detail getting Mingw running in MSYS on Windows. Stating that one must have Mingw running in MSYS should suffice. Similarly, the new changes repeat some previous information (e.g. the need to specify the name of the Chez executable with the SCHEME environment variable when building).

TLDR; I think comprehensive walkthroughs aimed at various levels of familiarity with tooling are really great resources, but (and this is my personal opinion, other maintainers may disagree) the INSTALL.md file should give all necessary information without repeating itself or readily available information on installing dependencies.

stale

[mattpolzin]

I think I'll close this PR soon as it seemed to stall out. Early iterations of this PR felt really good to me, but then as I noted above later change sets seemed to repeat already stated information and go into a degree of depth that felt more in line with a third party walk through tailored to a specific audience rather than a concise list of required steps to get Idris installed.

[melted]

Looks good to me as a Windows user.

[mattpolzin]

To be clear, I was going to close without merging in line with my comments about things I thought should be changed before merging it. If general consensus is that we should merge this as-is, that’s ok with me.