Skip to content
zalan-racz-gaijin edited this page Jun 17, 2024 · 5 revisions

This is the wiki of Dagor Shader Language Support for Visual Studio Code, a VS Code extension to support DSHL.

About this wiki

The goal of this wiki is to make it easier to understand how this project works. When I explain something, I try to give you some context, but I won't describe the underlying technologies in detail. For this, each page has a Useful resources section, where you can find links that give you more in-depth explanations. In these wiki pages, I'd like to focus on the project structure, ideas behind decisions, tips, and tricks.

The extension

This is a VS Code extension, and its goal is to add full language support for DSHL and HLSL. If you want to know more about the extension's features, read the README.md, and the CHANGELOG.md files. The extension is published under the BSD-3 license, which you can read in the LICENSE file. The extension is published, and it's available both in Visual Studio Marketplace, and in VS Code's extensions tab.

Language Server Protocol

The extension uses the Language Server Protocol to provide its features. The Language Server Protocol is basically a specification which standardizes IDE features like code completion, formatting, go to definition, etc. It splits the execution to 2 parts: the client and the server. The client (this repository) is an IDE-specific extension which starts the language server and sends requests towards it as the user interacts with the source code. The language server (don't confuse it with web servers) answers those requests. This means that although the client is IDE-specific, it's very thin and the language server does the heavy lifting, like analyzing the source code. The Language Server Protocol has many advantages:

  • the language server runs in a different process, therefore it won't block the IDE if the analyzation takes a lot of time
  • the communication is standardized, so the language server doesn't have to know the IDE's API and doesn't have to be written in the same language
  • don't have to write the language features for all the IDEs, you have to write the language server only once, and all client can use it

Syntax highlight, language configuration

While the syntax highlight, and the declarative language features are part of the client, those files are shared between the different clients, therefore stored in the language server's repository.

TODO

  • Microsoft is working on VS Code's WebAssembly support, they already wrote a blog post and then another one. about it. They also created a sample extension. At the moment the support is experimental and not advised for use in production, but hopefully, soon there will be proper WebAssembly support for VS Code, and we'll be able to run the shader compiler in every platform, and even in the browser.
  • It'd be a good idea to create an advanced mode or something similar, where you can select one specific interval combination. This way it'd be unambiguous which part of the code is executed and which part is not. With a Webview, and the Webview UI Toolkit it is possible do do it.
  • E2E tests only cover DSHL macros. It'd be nice to write tests for all the other DSHL and HLSL language constructs
  • Instead of manually releasing the new version, it'd be nice to create a CD pipeline that does this for us
  • Usually upgrading the dependencies are trivial, but ESLint requires a new configuration format, but there is a migrator

Reporting bugs

If you find a bug, create an issue, but please give me as much information as possible. If it's not obvious, what's the cause of the problem, please include the extension's version, VS Code's version, the operating system, create screenshots or videos, or anything that might be helpful.

Useful resources