[ doc ] Add Windows WSL usage #2985
Conversation
| Open Windows PowerShell as administrator and run: | ||
|
|
||
| .. code-block:: PowerShell | ||
|
|
||
| wsl --instal # enable Window to run a linux system | ||
| wsl --install -d Ubuntu # install a specific linux distro | ||
|
|
||
| A restart may be required. | ||
|
|
There was a problem hiding this comment.
I'm not sure we want to maintain WSL install instructions. Would it be better to link to the official MS docs (https://learn.microsoft.com/en-us/windows/wsl/install)?
There was a problem hiding this comment.
I thought about that, but it's too detailed. I like guides that are a copy pasteable single script, nay time i can search for more detailed docs. I can think of some alterantives:
- leave only the link
- leave the commands + link
- leave only the commands
What do you think is best?
There was a problem hiding this comment.
Hmm, yeah it's a question of balance... I definitely get where you're coming from, I am not particularly fond of "guides" that require you to be 5 tabs side-tracked every other step, so I think commands + link (with an "would you like to know more/advanced instructions" note) is the compromise to go with : )
|
|
||
| wsl -d Ubuntu idris2 # to run idris2 command in the current Windows directory | ||
|
|
||
| Or in alternative you can use vscode with wls and idris extensione combined. |
There was a problem hiding this comment.
Or in alternative you can use vscode with wls and idris extensione combined.
Or alternatively, you can use VSCode with WSL and the ``idris2-lsp`` extension for VSCode.
A footnote pointing to https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode might also be a good idea? (Similar to the discussion about WSL install instructions.)
There was a problem hiding this comment.
There are several extensions, which one do you reccomend? I think to link the "best" one as an example is a good idea
There was a problem hiding this comment.
Based off the number of downloads, this one? https://marketplace.visualstudio.com/items?itemName=bamboo.idris2-lsp
It also seems to be the recommended one from the other popular extension:
For Idris 2, the language-server based extension provides additional features, such as semantic highlighting. If you are using the latest version of Idris 2, it may provide a better experience.
| Open PowerShell and run: | ||
|
|
||
| .. code-block:: PowerShell | ||
|
|
||
| wsl -d Ubuntu # open a linux terminal |
There was a problem hiding this comment.
Replace this with "Open a WSL terminal"? (Rather than providing distro-specific instructions.)
Similarly, for the following bits of instructions, it would be good to have a disclaimer saying something like "The rest of this section assumes you are using an Ubuntu WSL, but the idea of the steps should work on most instances."
There was a problem hiding this comment.
I can understand that, the existing docs are very flexible about how to isntall and build things.
I come from web development where to install or build there is only one command to type, nothing to choose, just plain convention. I wrote these docs considering my experience trying to make it work, there were many things to choose, details to hunt down.
Ultimately my intention here is boost adoption, anybody within hours could get how to build idris in windows under wls, my intention is to provide a nobrainer.
At this point i think a good compromise would be a disclaimer on top like "This is a oneshot copypaste command to build, for more customization you find all the stuff in the docs"
| .. code-block:: PowerShell | ||
|
|
||
| wsl -d Ubuntu # open a linux terminal | ||
| apt update # it is necessary to install dependencies |
There was a problem hiding this comment.
Please change this to sudo apt update && sudo apt upgrade. This is to make sure the system is up to date, not to install dependencies.
It is generally bad practice to update the package info without also upgrading. You can accidentally break things by installing newer packages (in scope thanks to update) while older, non-supported versions of their dependencies are installed (due to lack of upgrade).
There was a problem hiding this comment.
I didn't know that, i thought the semver resolution was enough and also maybe we could save the user to upgrade the whole system. Anyway will change it as you suggested.
There was a problem hiding this comment.
It might be distro-dependent, I'm not sure. But better safe than sorry? ^^
|
|
||
| wsl -d Ubuntu # open a linux terminal | ||
| apt update # it is necessary to install dependencies | ||
| apt install make gcc chezscheme libgmp3-dev # install dependencies required for build from source |
There was a problem hiding this comment.
- You need to use
sudofor package installations. - There is a
build-essentialmeta-package which installs all the relevant tools (make,gcc, etc.)- Chez and GMP will still need a separate listing to be installed.
- Probably good to ask them to install the man-pages (documentation) as well:
manpages-dev?
There was a problem hiding this comment.
default wls installation has root user only (at least from what i know). But good idea to prepend sudo just in case the user created other linux users. Ok, i will update to build-essentials. What would the user need the man-pages for?
Thank you for all the precious feedback! (I'm learning a lot)
There was a problem hiding this comment.
The WSL documentation seems to suggest otherwise:
Once the process of installing your Linux distribution with WSL is complete, open the distribution (Ubuntu by default) using the Start menu. You will be asked to create a User Name and Password for your Linux distribution.
The man-pages would mostly be for trouble-shooting on the user's end. I guess they're not strictly required, but a lot of guides, StackOverflow answers, and similar refer to them as a reference point and/or further reading. So I figured it'd be best to include them : )
| cd Idris2 # move to the source code directory | ||
| make bootstrap SCHEME=chezscheme # builds the executable | ||
| make install # installs the executable | ||
| ln -s ~/.idris2/bin/idris2 /usr/local/bin/idris2 # add the binary to executable path |
There was a problem hiding this comment.
You'd need sudo (the destination is owned by root by default), however symlinks are almost always a bad idea (it is very easy to get the order of the arguments wrong, and it creates unnecessary complications in terms of where things are located in this case).
It would be better to instruct users to add the following line at the end of their ~/.bashrc file and restart their terminal:
export PATH="$HOME/.idris2/bin:$PATH"(This adds the default Idris2 install location to the magic variable that the shell searches for executables when you try to run a command.)
There was a problem hiding this comment.
I though about that, but is seems that commands like "wsl -D ubuntu idris2" do not pick up the ~/.bashrc i will test
There was a problem hiding this comment.
Any luck? I'm not familiar with that command, I've always just opened up a WSL terminal, and then done everything as I would on a regular linux terminal : )
There was a problem hiding this comment.
Yes, at least onmy machine a cannot make it work with bashrc. Anyway i think this feature is not worth the trouble
CodingCellist
added
documentation
|
@CodingCellist maybe i want to rethink the guide. Something along the lines: "here is an opinionated setup on windows"
In the form of a copy pasteable script, and leaving out all other details. What do you think? |
|
I thought more about your feedback, we could include both opinionated setup and general instructions. In the form of: Example enviroment setup on windows:
This is a step-by-step guide for an opinionated setup. It provides general instructions for each step and copy pasteble commands that should work in most cases for the hasty.
- install windows wsl
- see instructions [here](https://learn.microsoft.com/en-us/windows/wsl/install)
- or `wsl --install`
- install a linux distribution if you do not have already one
- see guide [here](other link)
- or `wsl --install -d Ubuntu`
- and so onI wait for feedback before rewriting. Thank you very much for the precious info, it is very appreciated. |
|
@freddi301 I really like the idea of the "opinionated setup for the hasty" note, followed by a nobrainer script! : ) Much as I personally would prefer to have both simple and generic instructions, it might be a bit too much both to maintain and have on the page (unless others disagree), so I think limiting the "Advanced/Custom Guide" to links to the relevant docs and something along the lines of "the idea is the same: WSL -> Chez Scheme -> Idris2 -> idris2-lsp" as instructions (with slightly more words), should be fine. I've left some replies to the changes requested. I hope this helps : ) |
|
Absolutey, i have all the feedback i need to rewrite it. Thank you! |
|
Any progress @freddi301 ? |
|
Lacking free time lately. I will eventually complete the PR |
|
For my personal usage i settled on installing idris 2 with pack inside a WLS and editing with VSCode + idris2-lsp extension |
Description
Add step by step instruction to use Idris 2 on windows easily.