CLI Usage

Synopsis

Usage: ./jz-hdl JZ_FILE --lint [--warn-as-error] [--color] [--info] [--explain] [--Wno-group=NAME] [--Eno-group=NAME] [--tristate-default=GND|VCC] [-o OUT_FILE]
       ./jz-hdl JZ_FILE --verilog [-o OUT_FILE] [--sdc SDC_FILE] [--xdc XDC_FILE] [--pcf PCF_FILE] [--cst CST_FILE] [--tristate-default=GND|VCC]
       ./jz-hdl JZ_FILE --rtlil [-o OUT_FILE] [--sdc SDC_FILE] [--xdc XDC_FILE] [--pcf PCF_FILE] [--cst CST_FILE] [--tristate-default=GND|VCC]
       ./jz-hdl JZ_FILE --alias-report [-o OUT_FILE]
       ./jz-hdl JZ_FILE --memory-report [-o OUT_FILE]
       ./jz-hdl JZ_FILE --tristate-report [-o OUT_FILE]
       ./jz-hdl JZ_FILE --ast [-o OUT_FILE]
       ./jz-hdl JZ_FILE --ir [-o OUT_FILE] [--tristate-default=GND|VCC]
       ./jz-hdl JZ_FILE --test [--verbose] [--seed=0xHEX] [--tristate-default=GND|VCC]
       ./jz-hdl JZ_FILE --simulate [-o WAVEFORM_FILE] [--vcd] [--fst] [--jzw] [--verbose] [--seed=0xHEX] [--jitter=CLOCK:PS] [--drift=CLOCK:PPM] [--tristate-default=GND|VCC]
       ./jz-hdl --chip-info [CHIP_ID] [-o OUT_FILE]
       ./jz-hdl --lint-rules
       ./jz-hdl --lsp
       ./jz-hdl --help
       ./jz-hdl --version

Simulation timing options:
  --jitter=CLOCK:PS       Add peak-to-peak clock jitter in picoseconds (may repeat)
  --drift=CLOCK:PPM       Add maximum clock drift in parts per million (may repeat)

Expansion safety options:
  --expansion-limits=repeat-count=<n>,repeat-bytes=<n>,apply-count=<n>,apply-growth=<n>
                           Override hard expansion limits (defaults: repeat-count=1024,
                           repeat-bytes=1048576, apply-count=1024, apply-growth=4096)

Path security options:
  --sandbox-root=<dir>     Add permitted root directory for file access
  --allow-absolute-paths   Allow absolute paths in @import / @file()
  --allow-traversal        Allow '..' directory traversal in paths

Modes

Flag	Description
--lint	Run all semantic checks and report diagnostics. No output files are generated unless -o is given.
--verilog	Compile to Verilog. Optionally emit constraint files (--sdc, --xdc, --pcf, --cst).
--rtlil	Compile to RTLIL (yosys intermediate representation).
--ast	Emit the parsed AST as JSON.
--ir	Emit the intermediate representation as JSON.
--test	Run all @testbench blocks in the file. See Testbench.
--simulate	Run all @simulation blocks in the file. See Simulation.
--alias-report	Print the net alias resolution report.
--memory-report	Print the memory inference and mapping report.
--tristate-report	Print the tri-state driver analysis report.
--chip-info	Print chip data for the given CHIP_ID (or list all supported chips if no ID given).
--lint-rules	List all diagnostic rule IDs and their descriptions.
--lsp	Start the Language Server Protocol server (stdio transport). See Editor Integration.
--help	Print usage information.
--version	Print the compiler version and git commit (e.g., Version 0.2.0 (abc1234)).

Common options

Option	Description
-o OUT_FILE	Write primary output to OUT_FILE instead of stdout.
--color	Force colored diagnostic output.
--info	Include informational diagnostics (not just warnings and errors).
--explain	Print detailed explanation under each diagnostic.
--warn-as-error	Treat all warnings as errors.
--Wno-group=NAME	Suppress WARNING-level diagnostics in the named group.
--Eno-group=NAME	Suppress ERROR-level diagnostics in the named group.

Constraint file options (with --verilog)

Option	Description
--sdc SDC_FILE	Emit Synopsys Design Constraints.
--xdc XDC_FILE	Emit Xilinx Design Constraints.
--pcf PCF_FILE	Emit Physical Constraints File (open-source toolchains).
--cst CST_FILE	Emit Gowin Constraints File.

Path security options

Option	Description
--sandbox-root=<dir>	Add an additional permitted root directory for @import and @file() paths. May be specified multiple times.
--allow-absolute-paths	Allow absolute paths in @import and @file() directives (disabled by default).
--allow-traversal	Allow .. directory traversal in paths (disabled by default).

By default, the compiler restricts all file paths to be within the directory containing the input file. See Path Security for details.

Tristate default

Option	Description
--tristate-default=GND	Convert internal tri-state nets to priority muxes with GND default.
--tristate-default=VCC	Convert internal tri-state nets to priority muxes with VCC default.

This option is accepted with --lint, --verilog, --rtlil, --ir, --test, and --simulate. It is rejected with --ast.

See Tristate Default for details.

Expansion safety options

Option	Description
--expansion-limits=repeat-count=<n>,repeat-bytes=<n>,apply-count=<n>,apply-growth=<n>	Override the hard expansion safety limits for @repeat and template @apply. Defaults: repeat-count=1024, repeat-bytes=1048576, apply-count=1024, apply-growth=4096.

Testbench options (with --test)

Option	Description
--verbose	Print all assertion results (pass and fail), not just failures.
--seed=0xHEX	32-bit hex seed for register/memory randomization. Default: 0xDEADBEEF.

Exit codes

Code	Meaning
0	All tests passed
1	One or more test failures
2	Runtime error (x/z observation, combinational loop, etc.)
3	Compile error in testbench file

Simulation options (with --simulate)

Option	Description
-o WAVEFORM_FILE	Output waveform file path. Default: <input_basename>.vcd, or the selected format's extension when --fst or --jzw is specified.
--vcd	Force VCD output format (default).
--fst	Force FST output format.
--jzw	Force JZW output format (SQLite-based).
--jitter=<clock>:<ps>	Add peak-to-peak clock jitter in picoseconds. May be specified multiple times.
--drift=<clock>:<ppm>	Add maximum clock drift in parts per million. May be specified multiple times.
--verbose	Print tick resolution, clock periods, and @run/@update events.
--seed=0xHEX	32-bit hex seed for register/memory randomization. Default: 0xDEADBEEF.

Examples

# Check a design for errors
jz-hdl design.jz --lint --color

# Check with full info-level output
jz-hdl design.jz --lint --info --color

# Compile to Verilog
jz-hdl design.jz --verilog -o design.v

# Compile to Verilog with tristate elimination
jz-hdl design.jz --verilog -o design.v --tristate-default=GND

# Compile to RTLIL for yosys
jz-hdl design.jz --rtlil -o design.il

# Compile with Gowin constraint output
jz-hdl design.jz --verilog -o design.v --cst design.cst

# Dump the AST for debugging
jz-hdl design.jz --ast -o design_ast.json

# View alias resolution
jz-hdl design.jz --alias-report

# View memory inference report
jz-hdl design.jz --memory-report

# View tristate analysis
jz-hdl design.jz --tristate-report

# List supported chips
jz-hdl --chip-info

# View chip details
jz-hdl --chip-info GW2AR-18

# Run testbenches
jz-hdl test_counter.jz --test

# Run testbenches with verbose output and fixed seed
jz-hdl test_counter.jz --test --verbose --seed=0xCAFE

# Run a simulation
jz-hdl sim_fifo.jz --simulate

# Run simulation with explicit output path
jz-hdl sim_fifo.jz --simulate -o fifo_waves.vcd

# Run simulation in FST or JZW format
jz-hdl sim_fifo.jz --simulate --fst
jz-hdl sim_fifo.jz --simulate --jzw

# Run simulation with clock jitter and drift
jz-hdl sim_fifo.jz --simulate --jitter=clk:200 --drift=clk:50

# Run simulation with verbose output and fixed seed
jz-hdl sim_fifo.jz --simulate --verbose --seed=0x1234

# Start the LSP server (used by editors, not invoked directly)
jz-hdl --lsp

Editor Integration

The --lsp flag starts a Language Server Protocol server over stdio. The server provides:

• Diagnostics — errors and warnings published on file open/change
• Hover — descriptions for JZ-HDL keywords and diagnostic rule codes
• Completion — @ directives and block keywords
• Go-to-definition — jump to declarations of modules, ports, wires, registers, etc.

VS Code

A VS Code extension is included in the vscode-ext/ directory. To install:

cd vscode-ext
npm install
npm run package:vsix

Then in VS Code: Extensions → ... → Install from VSIX and select vscode-ext/build/jz-hdl.vsix.

The generated .vsix file is build output and should not be checked into the repository.

Settings

Setting	Default	Description
jz-hdl.binaryPath	"" (system PATH)	Path to the jz-hdl binary. Leave empty to use the system-installed version.
jz-hdl.lsp.enabled	true	Enable or disable the language server.

Other Editors

Any editor with LSP support can use jz-hdl --lsp. For example:

Neovim:

vim.lsp.start({
    name = "jz-hdl",
    cmd = { "jz-hdl", "--lsp" },
    filetypes = { "jz-hdl" },
})

Emacs (with lsp-mode):

(lsp-register-client
 (make-lsp-client
  :new-connection (lsp-stdio-connection '("jz-hdl" "--lsp"))
  :activation-fn (lsp-activate-on "jz-hdl")
  :server-id 'jz-hdl))