ZHDL is a fork of TerosHDL, modified and maintained by narutozxp.

ZHDL

A VS Code extension for ASIC and FPGA development, with Verilog, SystemVerilog and VHDL editing, project management and tool integration.

Version 8.0.11

Live Verilog/SystemVerilog parsing now keeps completion, Hover and dirty-buffer Outline in sync with unsaved edits.
Live symbols include modules, ports, signals, instances, parameters, macros, functions, tasks, classes, typedefs and common SystemVerilog declarations.
Cross-file module, parameter and port completion uses current interfaces from other open project files.
The offline VSIX is smaller while retaining the parsers, Webview assets and bundled tools needed at runtime.
Live parsing remains experimental and disabled by default while large real-world projects receive further testing.

Features

Syntax highlighting, snippets and template generation.
Verilog and SystemVerilog keyword and symbol completion.
Cross-file module completion, instantiation templates, named port and parameter completion, and hierarchical port completion.
Go to definition, Hover information, Outline, hierarchy and dependency views.
Syntax checking, Verible style checking and code formatting.
HDL documentation, schematic viewing and state machine tools.
Integration with GHDL, Verilator, Icarus Verilog, Yosys, Vivado, Quartus, VUnit, cocotb and other HDL tools.

Module and port completion

The index first uses the ZHDL project containing the current file. Without a matching project, it uses the open Verilog and SystemVerilog files. Set the scope to workspace to index supported HDL files in the current workspace instead.

Configure indexing under Open Global Settings Menu → General. The settings are stored in ~/.zhdl_config.json:

{
  "general": {
    "general": {
      "indexing_scope": "openFiles",
      "live_parsing": false
    }
  }
}

indexing_scope accepts openFiles or workspace. Workspace scanning includes .v, .sv, .vh and .svh, and excludes common dependency and build directories. Saving through the settings page applies changes immediately; reload VS Code after editing the JSON file directly.

On a blank line inside a module body, type a module name and select it to insert an instance with named parameters and ports. Use Tab to edit the instance name, parameter values and connections. The generated comments show port direction and width when ZHDL can determine them.

Inside an existing instance:

Type . in the connection list to complete unconnected ports.
Type . in #(...) to complete parameters.
Type u_instance. to complete the instantiated module's ports.
Inside .port(...), completion uses signals visible in the current source context.

Indexing parses HDL syntax without preprocessing or elaboration. Interfaces generated entirely by macros may therefore be incomplete.

Live parsing for unsaved edits

Enable Live parsing (experimental) in Open Global Settings Menu → General to update Verilog and SystemVerilog completion, Hover and dirty-buffer Outline from unsaved content.

The first parse occurs when a file is opened. Later edits reuse its Tree-sitter syntax tree and normally update only affected declarations or regions. Other project files contribute lightweight module, parameter and port information; open unsaved project files contribute their current interfaces.

The live snapshot recognizes modules, ports, registers, nets, instances, constants, macros, functions, tasks, classes, typedefs, enum and struct members, interfaces, packages, programs, checkers, modports, properties, sequences and covergroups. Function arguments and local variables are limited to their parent container when completion and Hover choose visible symbols.

Current limitations:

Macros and includes are not expanded into compiler-level semantics.
Editing a header does not yet invalidate every file that depends on it through preprocessing.
Package imports, inheritance and other type relationships do not receive full elaboration.
Virtual documents can use local live parsing but do not receive every file-based project feature.
Large-project memory use and end-to-end UI latency still need broader field testing.

Disable live parsing to restore the saved-file indexing behavior.

Lint updates

Once a linter is configured and enabled, opening, editing and saving a file can refresh diagnostics. External lint tools generally process the complete content, so their runtime is separate from live Tree-sitter completion.

Offline use

The VSIX includes its HDL parsers, Yosys, Pyodide, SQL.js, required Python wheels, Webview assets and bundled native helper tools. The extension does not require a runtime download for these components.

Install a VSIX compatible with the environment where the extension host runs. With Remote SSH, WSL or containers, tool paths and native binary compatibility refer to that remote environment. External tools such as Vivado, Quartus, GHDL and Verilator must still be installed there before their integrations can work offline. Online documentation and optional downloads still require a connection.

Bundled helper versions:

Verible LSP: v0.0-4219-g3275ab72 for Linux x86_64 and Windows x64.
Universal Ctags: 6.2.0 (ab95af1) for Linux x86_64, macOS Intel and Windows x86.

Configuration and migration

File	Purpose
`~/.zhdl_config.json`	Global settings, tool paths, linters, formatting and indexing
`~/.zhdl_prj.json`	Project list and project data

On Windows, ~ corresponds to %USERPROFILE%. With Remote SSH, WSL or containers, these files belong to the user running the remote extension host.

ZHDL no longer automatically reads or writes TerosHDL's .teroshdl2_config.json and .teroshdl2_prj.json. Use Load Settings to import an old configuration, or copy the project file after closing the relevant extension hosts and backing up any existing .zhdl_prj.json.

The default build directory is ~/.zhdl/build. Output channels, commands and project views use zhdl identifiers; update custom keybindings that still refer to teroshdl.* commands.

Documentation and feedback

Acknowledgments

Thanks to Teros Technology and the TerosHDL maintainers and contributors. This project's foundational features and architecture come from their open-source work.

License

This project retains the upstream GNU GPL v3 license. Original author copyright notices are preserved.