Document how to use ZLS

Question

Document how to use ZLS

dnut opened this issue 8 months ago · comments

It is unclear how to use this extension. The README says this extension supports ZLS, but installing the extension is not enough to get that working. The README should explain how to get ZLS support.

The ZLS docs say:

Note You don't need to install ZLS or Zig manually

Using ZLS in Visual Studio Code is as simple as installing the official Zig Language extension (open in VSCode).

But the only thing you get after installing this extension is syntax highlighting and a bunch of non-functional commands. Nearly every command results in a message like command 'zig.zls.install' not found.

After spending a while trying to get this working, I eventually figured out some basic steps get this extension working with zls. These steps will get vscode to use its own installed versions of zig and zls.

run the "Zig Setup: Install zig" command (this is the only command that works at first)
restart vscode (important)
run the "Zig Language Server: Install Server" command
run the "Zig Language Server: Start / Restart server" command

Alternatively, you can use pre-installed zig and zls binaries with this extension, but the extension will not find them in your PATH automatically (contrary to what it says in the settings gui). You need to explicitly configure something like this:

{
    "zig.zigPath": "/usr/bin/zig",
    "zig.zls.path": "/usr/bin/zls"
}

Or you can do this for a workspace-specific toolchain:

{
    "zig.zigPath": "${workspaceFolder}/zig",
    "zig.zls.path": "${workspaceFolder}/zls"
}

As with the steps described above, you need to restart vscode to apply this configuration before you will be able to start zls.

Veikka Tuominen · Answer 1 · Tue Oct 10 2023 02:40:00 GMT+0800 (China Standard Time)

At first install the extension runs you through the setup to handle the paths.

But the only thing you get after installing this extension is syntax highlighting and a bunch of non-functional commands. Nearly every command results in a message like command 'zig.zls.install' not found.

That is a bug that I've not been able to reproduce.

Drew Nutter · Answer 2 · Tue Oct 10 2023 02:51:24 GMT+0800 (China Standard Time)

At first install the extension runs you through the setup to handle the paths.

I don't remember seeing this.

How do I reproduce a "first install" state? Here's what I'm doing:

uninstall the extension
remove any zig.* configuration items from settings.json
rm -rf $HOME/.config/Code/User/globalStorage/ziglang.vscode-zig/
restart vscode
install the extension

After this, I don't see any kind of wizard running me through a setup process.

That is a bug that I've not been able to reproduce.

Have you tried running the command to install zls while the extension is not yet configured to use any version of zig?

Veikka Tuominen · Answer 3 · Tue Oct 10 2023 03:22:56 GMT+0800 (China Standard Time)

How do I reproduce a "first install" state? Here's what I'm doing:

That should do it.

Have you tried running the command to install zls while the extension is not yet configured to use any version of zig?

That worked and I was able to confirm that #138 fixes it.

I'll try to make a release with #138 within the next weeks.

Drew Nutter · Answer 4 · Tue Oct 10 2023 04:37:12 GMT+0800 (China Standard Time)

How do I reproduce a "first install" state? Here's what I'm doing:

That should do it.

What should I expect to see in this situation? Is there some kind of pop-up? Is there a command I can run to manually trigger a setup wizard?

Drew Nutter · Answer 5 · Tue Oct 10 2023 04:54:13 GMT+0800 (China Standard Time)

I found it. There is a notification. I always have "do not disturb" mode enabled because my experience with vscode until now has been that notifications are useless and distracting noise. So the notification never appeared for me.

I still feel that it can't hurt to have some kind of concise documentation about the required manual configuration. Notifications are not a very reliable way to ensure user interaction, especially if you only show them once.

Veikka Tuominen · Answer 6 · Tue Oct 10 2023 04:56:00 GMT+0800 (China Standard Time)

Does it also block modals? I changed the setup messages to be modals in that PR.

Drew Nutter · Answer 7 · Tue Oct 10 2023 05:10:11 GMT+0800 (China Standard Time)

My guess is no but I'm not sure. Is there any easy way for me to test the code in the pr?

Veikka Tuominen · Answer 8 · Tue Oct 10 2023 05:52:00 GMT+0800 (China Standard Time)

These commands and restarting vscode should do it:

cd /tmp
git clone https://github.com/ziglang/vscode-zig --single-branch zls-versioning --depth 1
cd vscode-zig
npm install
npx vsce package
code --install-extension vscode-zig-0.4.3.vsix

Veikka Tuominen · Answer 9 · Tue Oct 10 2023 05:55:20 GMT+0800 (China Standard Time)

If you're talking about the zen mode, then I just tested it and it doesn't hide modals.

Drew Nutter · Answer 10 · Fri Oct 13 2023 23:25:04 GMT+0800 (China Standard Time)

It seems that modals still work with do not disturb. I tested your branch with do not disturb mode turned on, and I saw the popup window requesting me to select my zig path. However, I'm seeing two new issues in this branch.

First, there was this error. This does not happen in the marketplace version, where an 0.12 dev version of zls is installed successfully.

A prebuilt ZLS 0.11.0 binary is not available for your system. You can build it yourself with https://github.com/zigtools/zls#from-source

Later, I wanted to do some more tests. I uninstalled the extension and cleared the state as I described in a prior comment. I closed vscode and installed the extension from your branch again. This time I didn't see any modal to configure zig. I guess the state is being saved somewhere else to indicate that the first run process has already been completed? It's unclear to me how to trigger the modal again. With the marketplace version, I always see the notification after clearing the state.

I suppose you could show a notification every single time that the extension detects the zig or zls path is improperly configured, in addition to the modal on first run. That gets us back into the realm of notification spam, which is why I use do not disturb mode in the first place, so I'm not sure if that's desirable.

FYI, Do not disturb mode is not the same as zen mode. Do not disturb only prevents notifications from popping up on the bottom right side of the screen. To enable do not disturb mode:

click on the notification bell icon all the way on the bottom right of the window
in the popup that appears, click on the crossed out bell icon with the tooltip that says "Toggle do not disturb mode"

Veikka Tuominen · Answer 11 · Fri Oct 13 2023 23:31:13 GMT+0800 (China Standard Time)

First, there was this error. This does not happen in the marketplace version, where an 0.12 dev version of zls is installed successfully.

A prebuilt ZLS 0.11.0 binary is not available for your system. You can build it yourself with https://github.com/zigtools/zls#from-source

That is because the ZLS team has not yet uploaded the tagged versions to their new backend.

Later, I wanted to do some more tests. I uninstalled the extension and cleared the state as I described in a prior comment. I closed vscode and installed the extension from your branch again. This time I didn't see any modal to configure zig. I guess the state is being saved somewhere else to indicate that the first run process has already been completed? It's unclear to me how to trigger the modal again. With the marketplace version, I always see the notification after clearing the state.

Currently it uses globalState which is seemingly not reset on reinstall, I would also like to have an easier way to reset it so I'll probably change it to an option.

Drew Nutter · Answer 12 · Fri Oct 13 2023 23:54:26 GMT+0800 (China Standard Time)

That is because the ZLS team has not yet uploaded the tagged versions to their new backend.

After I saw the error message, I installed the marketplace version of the extension, and it installed 0.12-dev. So I think this error comes down to a change in behavior in the extension. But maybe it's an intended behavior...

Did you add some logic to check the version of zig so it would install the same version of zls? Previously, it was happy to install 0.12 even though my zig version was 0.11. With the new version, it instead has an error that it can't install zls 0.11 (which is my zig version).

Currently it uses globalState which is seemingly not reset on reinstall, I would also like to have an easier way to reset it so I'll probably change it to an option.

Any suggestions on how to clear this state? I tried this but it wasn't enough to trigger the modal to come back:

rm -rf $HOME/.config/Code/User/globalStorage/ziglang.vscode-zig/

Veikka Tuominen · Answer 13 · Sat Oct 14 2023 00:23:44 GMT+0800 (China Standard Time)

After I saw the error message, I installed the marketplace version of the extension, and it installed 0.12-dev. So I think this error comes down to a change in behavior in the extension. But maybe it's an intended behavior...

It'll work once the binaries are uploaded.

Did you add some logic to check the version of zig so it would install the same version of zls? Previously, it was happy to install 0.12 even though my zig version was 0.11. With the new version, it instead has an error that it can't install zls 0.11 (which is my zig version).

Yes, that is the main goal of the PR.

Any suggestions on how to clear this state? I tried this but it wasn't enough to trigger the modal to come back:

I'd guess the data is stired in one of the caches but the DB might contain data from other extensions as well. I've reset it by changing one of the commands to instead update the value in globalState to false.

Turning it into an option will make it easy to reset again.

Drew Nutter · Answer 14 · Sat Oct 14 2023 00:50:40 GMT+0800 (China Standard Time)

Turning it into an option

What does this mean exactly? I could imagine this meaning a few things

The extension already persists some internal state somewhere to indicate that the first-run wizard has completed, so it won't show the wizard again. This could instead be implemented by storing a value in settings.json to indicate its completion, which a user can easily delete to trigger the modal to come again. For example, "zig.firstRunConfigurationCompleted": true
Add a setting that allows users to select whether they only want to see the modal on the actual first run, or they want it to display any time the zig toolchain is not fully configured. For example, "zig.alwaysPromptIfMisconfigured": true

Veikka Tuominen · Answer 15 · Sat Oct 14 2023 01:14:20 GMT+0800 (China Standard Time)

The first one.

Dora · Answer 16 · Mon Oct 16 2023 03:52:19 GMT+0800 (China Standard Time)

I was also having issues with ZSL and Zig vscode extension.

run the "Zig Setup: Install zig" command (this is the only command that works at first)

restart vscode (important)

run the "Zig Language Server: Install Server" command

run the "Zig Language Server: Start / Restart server" command

These steps worked for me! Not sure if this was intended as I already had zig installed before any of this.

Drew Nutter · Answer 17 · Mon Oct 16 2023 08:08:08 GMT+0800 (China Standard Time)

@catdotjs

I already had zig installed before any of this.

After running those steps, you now have two separate versions of zig on your computer. The IDE won't use the version of that you installed. It will use its own version that this extension downloaded into vscode's internal state.

Veikka Tuominen · Answer 18 · Fri Oct 20 2023 21:39:37 GMT+0800 (China Standard Time)

A new version of the extension has been published, please try running through the setup with it.

Artem Kolichenkov · Answer 19 · Tue Dec 05 2023 02:00:59 GMT+0800 (China Standard Time)

A new version of the extension has been published, please try running through the setup with it.

Just tried it and seems like I'm facing exactly same issues described above (couldn't find zig in PATH, modal shown only once and never again, ZLS needs to be manually installed, etc.)
Workaround described in original post still works fine though.

I'd say it is worth mentioning in readme that ZLS can be installed via vscode command, I didn't realize that's an option and was getting ready to manually install it before bumping into this github issue.

Extension version: v0.5.1
OS: MacOS Ventura 13.1
VSCode version: 1.84.2 (Universal)

Veikka Tuominen · Answer 20 · Tue Dec 05 2023 02:29:46 GMT+0800 (China Standard Time)

Can you describe how you interacted with the modals? You can run the initial setup again by setting zig.initialSetupDone to false.

Artem Kolichenkov · Answer 21 · Tue Dec 05 2023 02:50:25 GMT+0800 (China Standard Time)

Can you describe how you interacted with the modals? You can run the initial setup again by setting zig.initialSetupDone to false.

hm, just tried to reproduce (and remember what I did the first time).
So, now everything kinda worked fine.

It might be on me the first time it didn't work, most probably I did the following:

See modal about zig path, click Use zig in PATH
Modal closes
Another modal opens up (about enabling ZLS)
Me not reading the text, thinking "oh, it couldn't find zig in path, let me specify it manually then"
I point it to zig binary, not ZLS
Modal closes silently, no error notifications are shown (not even Could not find zls in PATH that is displayed if you cancel zls part)

Veikka Tuominen · Answer 22 · Tue Dec 05 2023 06:51:58 GMT+0800 (China Standard Time)

Me not reading the text, thinking "oh, it couldn't find zig in path, let me specify it manually then"

I point it to zig binary, not ZLS

I was able to reproduce your error with this.

With initialSetupDone set to true I get a popup saying Client Zig Language Server: connection to server is erroring. Shutting down server. but during the setup that doesn't appear and it fails to complete the setup.

Veikka Tuominen · Answer 23 · Tue Dec 05 2023 07:17:24 GMT+0800 (China Standard Time)

I improved that behavior in f3f9969.

Closing this issue as resolved by #138.