-
Notifications
You must be signed in to change notification settings - Fork 373
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[ doc ] Add Windows WSL usage #2985
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -56,6 +56,44 @@ install with the command ``make install``. This will, by default, install into | |
|
||
IDRIS2_PREFIX ?= /usr/local | ||
|
||
On Windows | ||
------------------------- | ||
|
||
On Windows systems you can build and use Idris 2 from sources using WSL (Windows Subsystem for Linux). | ||
|
||
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. | ||
|
||
Open PowerShell and run: | ||
|
||
.. code-block:: PowerShell | ||
|
||
wsl -d Ubuntu # open a linux terminal | ||
Comment on lines
+73
to
+77
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I can understand that, the existing docs are very flexible about how to isntall and build things. |
||
apt update # it is necessary to install dependencies | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please change this to 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It might be distro-dependent, I'm not sure. But better safe than sorry? ^^ |
||
apt install make gcc chezscheme libgmp3-dev # install dependencies required for build from source | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The WSL documentation seems to suggest otherwise:
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 ~ # by default wsl will open in the current Windows directory, so we move to a directory inside the linux filesystem | ||
git clone https://github.com/idris-lang/Idris2.git # download source code from github | ||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You'd need It would be better to instruct users to add the following line at the end of their 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I though about that, but is seems that commands like "wsl -D ubuntu idris2" do not pick up the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, at least onmy machine a cannot make it work with bashrc. Anyway i think this feature is not worth the trouble |
||
exit # exit the linux terminal | ||
|
||
Open PowerShell in your source code directory and run: | ||
|
||
.. code-block:: PowerShell | ||
|
||
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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:
|
||
|
||
|
||
Installing from a Package Manager | ||
================================= | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
What do you think is best?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 : )