Skip to content
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.

Sign up for GitHub

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

Jump to bottom

[ doc ] Add Windows WSL usage #2985

Closed
wants to merge 2 commits into from
+38 −0
Closed

[ doc ] Add Windows WSL usage #2985

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
82e4a49
[ doc ] Add Windows WSL usage
May 14, 2023
3fd6fd9
fix: run on windows instructions
freddi301 May 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/source/tutorial/starting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Comment on lines +64 to +72
Copy link
Collaborator

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)?

Copy link
Author

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:

  • leave only the link
  • leave the commands + link
  • leave only the commands

What do you think is best?

Copy link
Collaborator

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 : )

Open PowerShell and run:

.. code-block:: PowerShell

wsl -d Ubuntu # open a linux terminal
Comment on lines +73 to +77
Copy link
Collaborator

Choose a reason for hiding this comment

The 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."

Copy link
Author

Choose a reason for hiding this comment

The 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.
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"

apt update # it is necessary to install dependencies
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Author

Choose a reason for hiding this comment

The 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.

Copy link
Collaborator

Choose a reason for hiding this comment

The 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • You need to use sudo for package installations.
  • There is a build-essential meta-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 ?

Copy link
Author

Choose a reason for hiding this comment

The 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?
Thank you for all the precious feedback! (I'm learning a lot)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ~ # 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Author

Choose a reason for hiding this comment

The 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 ~/.bashrc i will test

Copy link
Collaborator

Choose a reason for hiding this comment

The 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 : )

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Author

Choose a reason for hiding this comment

The 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

Copy link
Collaborator

Choose a reason for hiding this comment

The 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:

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.

- maraymond2/idris-vscode:README



Installing from a Package Manager
=================================

Expand Down