---
title: "Requirements and project setup"
---

# Requirements and project setup

The open and vendor tools the HDL module uses and their licences, how tools are found, the hdl.json project file, its target families, and the example project.

## Tools and licences

Every tool runs as a separate process that you install. None is bundled or linked; GPL tools (Icarus Verilog, GHDL, KLayout, netgen) are only ever run as programs. Tools are optional per capability: a missing tool disables only what needs it, with an install hint.

### Open tools

The OSS CAD Suite installs most of them.

| Tool | Used for | Minimum the Editor checks |
|---|---|---|
| Verilator | Lint; simulation | 4.200; 5.036 for cocotb |
| Icarus Verilog (`iverilog`, `vvp`) | Simulation | 11.0 |
| GHDL | VHDL lint and simulation | 2.0 |
| NVC | VHDL simulation | |
| VUnit (`pip install vunit_hdl`) | VHDL test cases | |
| cocotb 2 | Python testbenches | |
| SymbiYosys (`sby`), eqy | Formal proofs, equivalence | |
| Yosys | Elaboration, synthesis | 0.20 |
| nextpnr (iCE40, ECP5, Gowin Himbaechel, nextpnr-xilinx) with icepack, ecppack, gowin_pack, Project X-Ray's `fasm2frames` and `xc7frames2bit` | Place and route, bitstreams | |
| icepll, ecppll, gowin_pll | PLL configuration | |
| openFPGALoader | Programming | |
| Verible (`verible-verilog-ls`) or svls; vhdl_ls | Language servers | |
| OpenROAD, KLayout (0.30 for the PDKs' current DRC and LVS decks), Magic and netgen | ASIC flow | |

### Vendor tools

| Tool | Licence for the free route | Hardware steps need |
|---|---|---|
| AMD Vivado | Vivado ML Standard (free edition) covers Artix-7, Spartan-7 and small Zynq parts | An SP701 or AC701 board and its JTAG cable |
| Altera Quartus Prime | Lite (free) or Pro | A MAX 10, Cyclone or Agilex 3 board |
| Microchip Libero SoC with FlashPro Express | A free Silver licence | A PolarFire evaluation kit and FlashPro |
| Lattice Radiant with Radiant Programmer | A free licence | A CertusPro-NX or CrossLink-NX board |

Vendor installs are found in their Windows and Linux layouts; that discovery is modelled, **not run on Windows**. When a vendor build fails at a FlexNet licence check, the message says which feature failed, where the tool looked and what to set.

### How tools are found

Each tool is found on `PATH`, in an OSS CAD Suite install, in the vendor's usual install folders, or at `neuralInverse.hdl.paths.<tool>`, and its version is checked against a minimum where one is set. These path settings are restricted in untrusted workspaces. Tool ids include `verilator`, `iverilog`, `vvp`, `ghdl`, `nvc`, `vunit`, `yosys`, `nextpnrIce40`, `nextpnrEcp5`, `nextpnrHimbaechel`, `nextpnrXilinx`, `openFpgaLoader`, `openRoad`, `klayout`, `magic`, `netgen`, `sby`, `eqy`, `vivado`, `quartusSh`, `libero`, `flashProExpress`, `radiant`, `radiantProgrammer`, `questa`, `riviera`, `xcelium`, `vcs`, `vitisHls`.

Discovery of the open tools is verified on Linux. Vendor installs (Vivado, Quartus, Libero, FlashPro Express, Radiant, Radiant Programmer) are modelled.

## The project file: hdl.json

An HDL project is described by `hdl.json` at the top of the workspace folder (`neuralInverse.hdl.projectFile` changes the path). A JSON schema gives completion and validation. A design's options belong in `hdl.json`; settings hold only machine facts such as tool paths.

```json
{
  "name": "adc-monitor",
  "sources": ["rtl/*.v"],
  "top": "adc_monitor_top",
  "vhdlStandard": "08",
  "testbenches": [
    { "name": "adc_monitor_tb", "top": "adc_monitor_tb", "sources": ["tb/adc_monitor_tb.v"], "simulator": "icarus", "timeout": 120 },
    { "name": "safety_monitor_cocotb", "top": "safety_monitor", "simulator": "icarus", "cocotb": "tests/test_safety_monitor.py" },
    { "name": "crc16_vunit_ghdl", "vunit": "sim/run.py", "sources": ["vhdl/crc16_ccitt.vhd", "sim/tb_crc16_ccitt.vhd"], "simulator": "ghdl" }
  ],
  "targets": [
    { "name": "ecp5_lfe5u25", "family": "ecp5", "device": "25k", "package": "CABGA256", "constraints": "constraints/ecp5_lfe5u25.lpf", "frequency": 40 },
    { "name": "artix7_vivado", "family": "xilinx", "device": "xc7a35tcsg324-1", "constraints": "constraints/artix7_xc7a35t.xdc", "frequency": 40 }
  ],
  "formal": ["formal/safety_monitor.sby"]
}
```

| Key | What it holds |
|---|---|
| `sources` | Globs of design files (language from the extension); include folders and defines |
| `top` | The top-level design unit |
| `vhdlStandard` | `87`, `93`, `93c`, `00`, `02`, `08` (default) or `19` |
| `testbenches` | Each with its top unit, extra sources, simulator (`verilator`, `icarus`, `ghdl` or `nvc`), timeout, and a `cocotb` test module or a `vunit` run script |
| `targets` | Each FPGA target: `name`, `family`, `device`, `package` (required for `ice40` and `ecp5`), `constraints`, `top`, `frequency`, `board` or `cable` for programming, and vendor sections (`vivado`, `quartus`, `libero`, `radiant`) |
| `formal` | Globs of SymbiYosys files; every `.sby` file by default |
| `asic` | Chips: PDK, top unit, clock and period, utilisation, aspect ratio, pads; see [ASIC](https://neuralinverse.com/docs/modules/hdl/asic/) |
| `hls` | Vitis HLS components (Vivado targets); see [IP, packaging and HLS](https://neuralinverse.com/docs/modules/hdl/ip/) |
| `includeDirs`, `defines` | Folders searched for `` `include `` files, and Verilog macros |
| `buildDirectory` | Where simulation, synthesis and place and route write their output; `build/hdl` by default |

### Target families

| `family` | Flow |
|---|---|
| `ice40` | Lattice iCE40 with Yosys and nextpnr |
| `ecp5` | Lattice ECP5 with Yosys and nextpnr |
| `gowin` | Gowin with Yosys and nextpnr |
| `xc7` | AMD 7-series (Artix, Kintex, Spartan, Zynq) with the open openXC7 flow |
| `xilinx` | AMD with Vivado in batch mode |
| `intel` | Altera with Quartus Prime in batch mode |
| `microchip` | PolarFire, PolarFire SoC, SmartFusion2, IGLOO2 and RTG4 with Libero SoC in batch mode (not yet run against Libero SoC) |
| `lattice` | CertusPro-NX, Certus-NX, CrossLink-NX, MachXO5-NX, Avant, iCE40 UltraPlus with Radiant in batch mode (not yet run against Radiant) |

`gowin`, `intel` and `microchip` targets also need `chipFamily`.

## Open an existing project, or start a new one

- A Vivado, Quartus, Libero, Gowin or Lattice project is imported into `hdl.json`, and Vivado, Quartus, Libero and Radiant project files can be edited in place for teammates who stay in the vendor IDE: see [Open and edit vendor projects](https://neuralinverse.com/docs/modules/hdl/vendor-projects/).
- **New Project...** creates `hdl.json` and a project skeleton from a part or a board read from your installed tools: see [New project from a part or board](https://neuralinverse.com/docs/modules/hdl/new-project/).

## The example project

The ADC monitor example is the realistic design every HDL screenshot was taken from: a dual-channel ADC capture and filter pipeline with a safety monitor, two clock domains, a UART command path, VUnit and cocotb testbenches, formal properties, a Vivado project and a Quartus revision. You may use, modify and ship it and designs derived from it without restriction. It is an example, not a certified safety function.

Verified on Linux (x86-64), 2026-10-11, with the open tools: Verilator 5.020 lint, Icarus Verilog 12.0 system testbench, cocotb 2.1.0, VUnit 4.7.1 on GHDL 4.1.0 and NVC 1.23.0, SymbiYosys proofs, ECP5 and openXC7 Artix-7 builds, and the ASIC flows. **Not built with Vivado or Quartus, and not run on hardware.** Timing figures are nextpnr estimates, not sign-off timing.