Quick start

From a folder of Verilog to an interactive schematic in one command, a guided tour of the viewer, then the planning loop.

1. Mark the top module

Add a comment above the module you want to open first:

// verilens: top
module top ( ... );

Without it, VeriLens picks the one module nothing else instantiates. If there are several, the first wins and the Modules tab lets you switch. You can also pass -t name to the launcher.

2. Run the launcher

./verilens path/to/rtl/                # a directory, or any list of .v / .sv files
./verilens rtl/ -l layout.yaml         # with layout rules
./verilens rtl/ -t my_top -o out.html  # choose the top and the output file
./verilens --help                      # also: --dev, --port N, --no-open, --rebuild

The launcher builds gen_ast and the viewer bundle if they are missing, parses your sources, writes <name>.verilens.html next to a <name>.verilens.ast.json, and opens the HTML in your browser. The HTML is self-contained: send it to a colleague and it works offline.

Parser warnings (for example an identifier that is not declared, or a width mismatch) are printed but do not stop the run. Modules that are instantiated but not found in your inputs are drawn as dashed black boxes.

3. Guided tour

The frame below is the viewer with the demo design loaded. Press Start tour; each step boxes one part of the interface and performs the action for you. You can also use the viewer directly.

ReadyPress Start tour. Steps go through the toolbar, the hierarchy tree, module expansion, net highlighting, the inspector, the layout editor and the diagnostics.

This page is being viewed from a local file, so the browser does not let the tour reach into the frame. Serve the folder over HTTP or use the hosted site; the viewer itself still works below.

Mouse and keyboard

Action	Effect
Drag on empty canvas	Pan. Dragging on a component, port or wire does nothing: nothing on the canvas is movable or editable.
Mouse wheel	Zoom around the pointer.
Click a component	Select it: red fill; its drivers turn green, its sinks blue, cells that are both turn yellow (feedback). The inspector shows details.
Click a wire or a boundary terminal	Select the net: orange highlight everywhere the net is visible, including inside expanded children and in the parent.
Click `[+]` / `[−]`	Expand or collapse that instance in place. Never starts a pan.
Click empty canvas	Clear the selection.
`Esc`	Clear the selection.
`f`	Fit the whole schematic (same as Fit design).
Touch drag	Pans only from the background, like the mouse.

Reading the schematic

Module instances are blue boxes with a header: the [+] toggle, the instance name, and the module name on the right. Collapsed boxes show the module name in the middle. Dashed grey boxes are black boxes: modules that were instantiated but not found in the inputs.
Primitives use schematic symbols where one exists (and/or/xor/not, mux, +, −, ×, =, <, shifts), a register symbol for always_ff blocks, and a labelled box for always_comb and anything unknown.
Ports are small square pins on the box edge with their name and [n:0] width inside. A hollow red circle marks an unconnected input.
Wires are thin for single bits and thicker for buses. The net name (and width) sits at the driver end; [3:0] labels at a sink mean only that slice is connected. A filled dot is a branch; a plain crossing is not a connection.
Boundary terminals are the module's own ports: pentagon flags on the left (inputs) and right (outputs).
Constants are small yellow boxes with the literal text.
Feedback wires (signals flowing right-to-left) run below the drawing and come back up next to their sink.

4. Plan the layout (optional)

Start the dev server with your files preloaded:

./verilens rtl/ -l layout.yaml --dev

Open the Layout tab, edit the rules, press Apply. Rules that cannot hold are listed with the scope and rule id, and the previous layout stays on screen. Edit the YAML file on disk and press Reload files to re-read it. When it looks right, Export HTML writes the final page with the rules embedded. The DSL is documented in Layout DSL.

5. A complete example

The repository ships a five-stage processor in core/tests/examples. This is the exact command behind the ProcBase example:

cd core/tests/examples
../../../verilens ProcBase.v ProcBaseDpath.v ProcBaseCtrl.v DropUnit.v ProcDpathAlu.v ProcDpathImmGen.v \
  IntMulAlt.v Lookahead.v muxes.v arithmetic.v regfiles.v tinyrv2_encoding.v -l ProcBase.layout.yaml