How tree-sitter/tree-sitter-verilog works
Project type and purpose
• This is a language-grammar plugin project (“tree-sitter-verilog”) for the Tree-sitter parsing library. It provides a SystemVerilog grammar and parser implementation in C, plus multi-language bindings (Node, Python, Go, Rust, Swift).
File structure
• Top-level:
• Core grammar & parser:
– src/grammar.json, src/node-types.json (node-type definitions)
– src/parser.c (C parser entry point)
– grammar.js (JavaScript helper)
• Bindings (bridge between the core C library and each target language):
– bindings/c (headers, pkgconfig)
– bindings/node (binding.cc, binding_test.js, index.js/.d.ts, binding.gyp)
– bindings/python (CPython extension, tests, packaging)
– bindings/go (cgo wrapper, tests)
– bindings/rust (build.rs, lib.rs, Cargo.toml)
– bindings/swift (Xcode project, headers, tests, Package.swift)
• Build & packaging files:
– CMakeLists.txt, Makefile for C build
– Cargo.toml/lock for Rust
– package.json + lock + binding.gyp + eslint.config.mjs for Node
– setup.py, pyproject.toml for Python
– Package.swift + Package.resolved for Swift
– go.mod/sum for Go
• CI / deployment:
– .github/workflows (lint, ci, publish)
• Tests & examples:
– test/corpus (Verilog test files)
– examples/module.v
README for architectural clues
• Confirms the project’s sole responsibility is providing the SystemVerilog grammar for Tree-sitter.
• Shows install/test instructions per platform/package manager.
a. Main components
1. Core Parser Component
• Grammar specification (grammar.json, node-types.json)
• Generated parser C code (parser.c + tree_sitter headers)
2. Build & Packaging Layer
• C build toolchain (CMake/Make)
• Language-specific build scripts (Cargo, setup.py, binding.gyp, Package.swift, go build)
3. Language Bindings
• Node.js (N-API / NAN)
• Python (CPython C extension)
• Go (cgo)
• Rust (FFI + build.rs)
• Swift (Clang module + Swift package)
4. Consumers / Clients
• JavaScript programs (npm)
• Python scripts (pip)
• Go applications
• Rust crates
• Swift apps
5. CI & Publishing
• GitHub Actions workflows
• Artifacts (npmjs.org, crates.io, PyPI, homebrew? not explicit)
b. Relationships & interactions
• Developer runs “tree-sitter generate” or builds the C core → outputs a shared library (libtree-sitter-verilog.so/.dylib/.dll).
• Each language binding references the shared library (or static lib) via FFI.
• Package manager tools invoke build scripts to compile the C core plus wrapper.
• Client code imports the binding package, calls the parse API to generate syntax trees.
c. Architectural patterns & design principles
• Plugin/Grammar pattern: core grammar + runtime parser library.
• Polyglot FFI layer: one codebase with multiple language adapters.
• Single-source grammar, generated artifacts reused across bindings.
• CI-driven release pipelines for each package registry.
d. Key technologies & frameworks
• Tree-sitter (parser generator)
• C / ANSI C for core parsing
• N-API/NAN for Node.js extension
• CPython C API for Python
• cgo for Go
• Rust’s FFI + Cargo
• Swift Package Manager + Clang module maps
• GitHub Actions