Document how to use ZLS

[dnut]

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.

1. run the "Zig Setup: Install zig" command (this is the only command that works at first)
2. restart vscode (important)
3. run the "Zig Language Server: Install Server" command
4. 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.

[Vexu]

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.

[dnut]

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:

1. uninstall the extension
2. remove any zig.* configuration items from settings.json
3. rm -rf $HOME/.config/Code/User/globalStorage/ziglang.vscode-zig/
4. restart vscode
5. 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?

[Vexu]

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.

[dnut]

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?

[dnut]

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.

[Vexu]

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

[dnut]

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

[Vexu]

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

[Vexu]

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

[dnut]

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:

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

[Vexu]

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.

[dnut]

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/

[Vexu]

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.

[dnut]

Turning it into an option

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

1. 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
2. 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

[Vexu]

The first one.

[catdotjs]

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

1. run the "Zig Setup: Install zig" command (this is the only command that works at first)
2. restart vscode (important)
3. run the "Zig Language Server: Install Server" command
4. 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.

[dnut]

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

[Vexu]

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

[ArtemKolichenkov]

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)

[Vexu]

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

[ArtemKolichenkov]

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)

[Vexu]

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

[Vexu]

I improved that behavior in f3f9969.

Closing this issue as resolved by #138.

[joshuabezaleel]

@dnut Do you know any workaround, even the manual one, that I can use to get the ZLS work for this one? 🙏

I keep encountering on this one as well on VSCode. No autocomplete or any other language server features, which makes it unable to code in Zig 😞

The pop-up/modal showing message of installing ZLS on the bottom-right on the VSCode was shown, and I have clicked OK on that. The message seems like it's downloading the tarball but after the download is finished, nothing happened at all, neither after I restarted the VSCode.

All VSCode command related to ZLS keep getting the error message of Command 'Zig Language Server: Start / Restart Server' resulted in an error (command 'zig.zls.startRestart' not found) as well 😢

This is my VSCode settings.json

{
    "diffEditor.ignoreTrimWhitespace": false,
    "editor.find.autoFindInSelection": "multiline",
    "debug.disassemblyView.showSourceCode": false,
    "window.zoomLevel": -1,
    "zig.path": "/Users/admin/Library/Application Support/Code/User/globalStorage/ziglang.vscode-zig/zig_install/zig",
    "zig.zigPath": "/opt/homebrew/bin/zig",
    "zig.initialSetupDone": true,
    "zig.formattingProvider": "zls",
    "zig.zls.path": "/Users/admin/Library/Application Support/Code/User/globalStorage/ziglang.vscode-zig/zls_install/zls"
}

Any help is much appreciated here, thank you lots in advance folks! 🙏