bug: ambiguous discussion of Language Server Integration

[RossBoylan]

Is there an existing issue for this?

• I have searched the existing issues

Description

The extension page contains a discussion of Language Server Integration, screenshot below. The discussion is ambiguous in several ways.

By default, Modern Fortran will attempt to use it [the language server] for hover, autocompletion, symbols and Go to & Peeking into definitions.

So if the language server is unavailable, what happens? The current wording suggests both that there may be fallbacks for those functions, so they would still work, and that the functions won't work without the server.

Allow for fortls to be automatically installed with pip or Anaconda and if the location where fortls is installed is not in your PATH point VS Code to the fortls location by setting

Does this need to be done before installing the extension?
This suggests the plugin will automatically install the language server, but it is not clear that that is the case.
If the extension does ordinarily automatically install fortls, what happens if it is already installed?

And the advice about setting fortran.fortls.path seems as if it's something that can only be done once the extension is installed, so it wouldn't help with the installation process itself. But maybe VSCode lets one set options before the corresponding package is installed?

Screenshots

Expected Behaviour

Clear instructions about what to do to setup the extension properly, including when to do those things.

Version of Modern Fortran

3.2.0

Version of Visual Studio Code

1.78.2

Platform and Architecture

Windows

Additional Information

I previously interpreted the instructions as meaning that I should install fortls before installing the extension. Looking at them more closely, it now seems to me that it is installed automatically (though presumably Python is not).

[gnikit]

So if the language server is unavailable, what happens? The current wording suggests both that there may be fallbacks for those functions

There are fallbacks for some of the functions, and they are (obviously) not as good as using a language server, hence why we don't recommend using them.
If you search through the settings, you will see three options, under General that by default use fortls.

Using the Built-in/Both option (where appropriate) will enable the fallback functionality.

If you don't want to use the Language Server (for now that is only fortls) you can disable it by setting

or via the JSON settings file

"fortran.fortls.disabled": true

This suggests the plugin will automatically install the language server,

Yes. The problem is that some users don't have the --user install location of pip in their $PATH. pip will, very clearly, throw a series of warnings if that is the case, for the User to add this new location to their $PATH.
However, if the user ignores the warnings, which they often do, when Modern Fortran tries to spawn a subprocess where it assumes that fortls is a binary reachable in your $PATH it will fail.

The option

Is meant to address the above problems. Instead of the user having to edit their global $PATH variable they can instead use the path absolute or relative to the root of the workspace to fortls binary that lives somewhere in your system.

If the extension does ordinarily automatically install fortls, what happens if it is already installed?

The extension prompts it does not install fortls without the user's knowledge.
If you have fortls and the extension can detect it won't install it, as it's common for most VSCode extensions with external dependencies.

And the advice about setting fortran.fortls.path seems as if it's something that can only be done once the extension is installed, so it wouldn't help with the installation process itself.

1. fortran.fortls.path as mentioned previously has nothing to do with the installation process. It's the path where the user tells the Modern Fortran extension to launch the Language Server from.
2. That settings can be set in the settings.json manually if one wishes to before installation of the extension.
3. For changes related to the Language Server you can:

• Restart the Language Server through the command palette, to use the new fortran.fortls.path
• Restart VS Code for the settings to take effect

But maybe VSCode lets one set options before the corresponding package is installed?

Not really common practice amongst users, but see 2. from above.
A full list of what the extension offers in terms of settings, commands, languages, etc. can be found on the extension's tab with the name FEATURE CONTRIBUTIONS

... it now seems to me that it is installed automatically (though presumably Python is not).

Python comes pre-installed with most major OSs, and if not the user can install it quite trivially via multiple ways.
We are not a Python extension. That aside, there is a Python extension for VS Code and even they don't install Python for you (for a plethora of reasons).

I can't see users being particularly happy with the idea of a "random" VS Code extensions installing large development environments in their computers just to get the extension to perform a certain way. We use prompts, walkthroughs, documentation and Q&A to instruct users on how to configure their underlying dev environment.

[RossBoylan]

First, thanks for the information.

Second, the reason I reported this as a bug is that I think the documentation needs to be clearer.

On to some of the specifics.

I think you're saying that if fortls is unavailable the functionality it provides is unavailable in the default settings, though for some of them one can go into the settings and enable (inferior) fallbacks. Is that right?

Does the default install attempt for fortls use --user even if VSCode is a system install? If the user is running with elevated privileges?

fortran.fortls.path: the reason setting this in advance seemed relevant is that I presumed it could affect whether the installer was able to find an existing installation. You answered one of my questions: one can set the option even before the fortran extension is installed, even if that's an unusual move.

The other wild-card in this, at least on MS-Windows, is that the file that is run is fortls.exe. I presume if fortls.exe has trouble finding the right Python interpreter there will be trouble, but the details are opaque to me--as well as not being the responsibility of this extension.

I wasn't suggesting Python should be installed automatically; I was implicitly suggesting the installation instructions should recommend installing it if you don't have it, before installing the extension. The MS-Windows user I was helping did not have it on her system, and I think that's typical for MS-Windows.

By the way, she was very pleased to see the syntax coloring, even if the other features aren't working yet for her!

[gnikit]

Second, the reason I reported this as a bug is that I think the documentation needs to be clearer.

We wouldn't classify issues related to documentation as software bugs. Also, currently, like many other VSCode extensions, we don't have an explicit documentation page.

I think you're saying that if fortls is unavailable the functionality it provides is unavailable in the default settings, though for some of them one can go into the settings and enable (inferior) fallbacks. Is that right?

Yes

Does the default install attempt for fortls use --user even if VSCode is a system install? If the user is running with elevated privileges?

We use pip as shown in the Task output of the install process (you can see the full command that is run). Install processes never run with elevated privileges.

The other wild-card in this, at least on MS-Windows, is that the file that is run is fortls.exe. I presume if fortls.exe has trouble finding the right Python interpreter there will be trouble, but the details are opaque to me--as well as not being the responsibility of this extension.

That would only happen if you have a broken Python installation. Other than adding a step in Walkthroughs to check your Python version I don't think there's much more that can be done.

I think that's typical for MS-Windows.

I don't think that's necessarily the case.

• with IntelOne API Python comes bundled
• With WSL Python comes bundled with Ubuntu
• With MSYS/Chocolatey, Python can be installed (I don't think it's installed by default when installing the GNU compiler suite)

Other than NAG, is there another Fortran development setup that I am missing on Windows?
How were you planning on compiling the Fortran code?

[RossBoylan]

Does the default install attempt for fortls use --user even if VSCode is a system install? If the user is running with elevated privileges?

We use pip as shown in the Task output of the install process (you can see the full command that is run). Install processes never run with elevated privileges.

I'm not familiar with Task output. Is this the OUTPUT tab in the terminal pane (probably not the right name for it--the one on the bottom right of VSCode), and select Tasks from the dropdown?

I think that's [no Python] typical for MS-Windows.

I don't think that's necessarily the case.

I think this campus has 10K MS-Windows installations without Python.

* with IntelOne API Python comes bundled

* With WSL Python comes bundled with Ubuntu

* With MSYS/Chocolatey, Python can be installed (I don't think it's installed by default when installing the GNU compiler suite)

Other than NAG, is there another Fortran development setup that I am missing on Windows? How were you planning on compiling the Fortran code?

You're missing the non-development environment 😄 .

(Another way to get Python on MS-Windows is to install MS Visual Studio--not Code--and elect Python support. I have a feeling the Intel Fortran compiler uses Visual Studio, so maybe that's covered indirectly by your list.)

The users are not Fortran developers (or developers at all) and do not have any Fortran development environment. They are using VSCode to browse the source code. I am a developer, but am not responsible for the Fortran code, which is programmed by a consultant. So I don't have a Fortran development environment either. The typical usage is that we get a new version of the code + compiled program, discover some strange outputs, and then go through the code to see what produced them. I'm really impressed that my colleagues, who are not coders, can look at Fortran code and make sense of it.

Anyway, they've had trouble getting fortls working, and I did as well. I think I got it working by entering an explicit path, but that hasn't done the trick for others.

[gnikit]

You're missing the non-development environment 😄 .

I see, that I did not expect. Unfortunately, the extension relies on some development environment being present; Python 3.7+ for fortls and gfortran/ifort/ifx/lfortran/nagfor for linting. You can disable both of these features and you will still be able to use the extension in it's simplest form.

You can install Python through the Microsoft Store. Intel OneAPI ships with their own optimised version of Anaconda, which I don't think it's what is available through Visual Studio. Either way I would sent an email to the IT department/sys admins to install some of these tools in the MS machines.

For a general Windows computer with Python, creating a virtual environment, installing fortls and pointing Modern Fortran to it should look something like this (assuming you are at the root of your project, i.e. directory where VS Code has been opened in).

python -m venv venv
venv\Scripts\activate.bat
python -m pip install fortls
:: "fortran.fortls.path": "${workspaceFolder}\\venv\\Scripts\\fortls.exe
:: if not in venv use full Windows path  to fortls.exe, since pip install --user location is not in PATH by default

You can apply the following steps using the default Python environment (no venv) but you should probably track down where that installs the fortls.exe binary.

If that is not possible I would suggest using the following 2 options:

  "fortran.linter.compiler": "Disabled",
  "fortran.fortls.disabled": true,

An other alternative, that requires no local setup other than a browser is; if you have access to an internet connection, and if you have/can have GitHub accounts, and if you are allowed to upload your code to GitHub (either in a private or public repo) you could then use Codespaces: https://github.com/features/codespaces.
I understand that these are a lot of ifs, but it could be a potential solution for you and your colleagues.