# parsevhdl

> IEEE LRM-compliant VHDL parser with Java, Python, Tcl APIs

- Catalog id: `Parsevhdl`; bundle: `parsevhdl`; latest version 20261018
- Documentation page: https://edautils.com/VHDLParser.html
- Keywords: VHDL parser, IEEE 1076, VHDL-2008, Java API, Python API, Tcl API
- Terms: as stated on edautils.com, EDAUtils tools are free for commercial and academic use, with no license server. The bundle's own metadata says: "Free to evaluate with the bundled licence; commercial licences from help@edautils.com". Licence prerequisites per tool are under "How an agent runs it".
- This file: https://edautils.com/capabilities/parsevhdl.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Parsevhdl (latest file `parsevhdl-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/free-vhdl-parser/files/parsevhdl/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/parsevhdl-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

## How an agent runs it

The following is the AGENTS.md shipped at the root of the bundle.

The VHDL parser bundle. Its main job is to be a Java API (javadoc in `doc/html`), and it also ships two
command-line launchers built on a compile-then-load flow (a third, `elabvh`, is documented here but
ships only in the designplayer-shell, baya-shell and ipxact-shell bundles, main class
`com.eu.miscedautils.shell.elabvh`, because its `-upf` needs the UPF backbone those bundles carry). VHDL files are analysed (`-compile`) into
a work library on disk. Then a design unit is loaded back (`-load -du`), optionally
elaborated, and decompiled to a VHDL file (default `decompiled.vhd`). The bundle ships
`lib/vhdlparser.jar` and the precompiled std/ieee/misc libraries under `vhdl_pkgs/`.

| Launcher | Main class (Unix launcher, last `MAIN=`) | Launcher CLASSPATH | Tool prefix / log |
|---|---|---|---|
| `parsevhdl` | `com.eu.miscedautils.vhdlparser.ReadVHDLAndPrintBack` | `lib/vhdlparser.jar` | `ParseVHDL` / `ParseVHDL.log` |
| `anvh` | `com.eu.miscedautils.vhdlparser.anvh` | `lib/designplayer.jar` (not shipped, see below) | `anvh` / `anvh.log` |
| `elabvh` (shell bundles only) | `com.eu.miscedautils.shell.elabvh` | `lib/designplayer.jar` / `lib/baya.jar` | `elabvh` / `elabvh.log` |

**Known launcher defect:** `bin/anvh` sets `CLASSPATH=$EDAUTILS_ROOT/lib/designplayer.jar`,
but this bundle ships only `vhdlparser.jar` (`bundle_jar_files.csh`: `parsevhdl` -> `vhdlparser.jar`).
The classes are in `vhdlparser.jar`, so run them as
`java -cp $EDAUTILS_ROOT/lib/vhdlparser.jar <main class> ...` until the launchers are fixed. The
`.bat` launchers set no CLASSPATH and rely on `setup_env.bat`.

### Language support

- One grammar (`Vhdl2019Lexer`/`Vhdl2019Parser`, classes `FVhPVhdl2019ParserImpl` and friends)
  reads every revision of IEEE 1076 -- VHDL-87, -93, -2002, -2008 and -2019 -- with no
  `-std` switch. Words a later revision reserved (`context`, `force`, `release`, `parameter`,
  `protected`, `private`, `view`, `default`, ...) are still accepted as ordinary names, so a
  legacy source that uses one as a signal or entity name analyses unchanged.
- IEEE 1076-2019 24.2 conditional analysis (`` `if/`elsif/`else/`end ``, `` `warning ``, `` `error ``)
  is resolved before parsing. Any other tool directive (for instance `` `protect ``) is reported
  as Error 9440, so an encrypted IP envelope does not analyse.
- PSL (IEEE 1850) directives, `default clock`, `property`/`sequence` declarations and
  `vunit`/`vprop`/`vmode` units are accepted and kept as the source text they were written in.
- Decompiling (`-load ... -out`) prints back what the data model holds. Every construct parses;
  these print differently from the source, with the same meaning: a 2019 sequential `block`
  inside a process or subprogram is printed in line (its declarations move to the enclosing
  process or subprogram); `inertial` in a port map and `parameter` before a parameter list are
  dropped; a package declared inside a protected type body is not printed.

### Where it ships

Its own bundle, `parsevhdl.tar.gz` (flow `parsevhdl`; release tree
`release_scripts/parsevhdl/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell** and
**designplayer-shell** bundles (`bin/anvh`, `bin/parsevhdl` running the shell's jar; this guide as
`tools/parsevhdl/AGENTS.md`, examples under `tools/parsevhdl/examples/`).

### Prerequisites

- Java on `PATH` (the launcher runs plain `java`). Use Java 11 or newer (Java 21 recommended: the
  release is built and regression-tested with OpenJDK 21); the bundled JAXB and Eclipse libraries
  are class-file version 55, so a Java 8 runtime fails with `UnsupportedClassVersionError`.
- `EDAUTILS_ROOT` = the unpacked bundle directory (must contain `bin/` and `lib/`). The
  launcher exits 1 with "Environment variable EDAUTILS_ROOT is not set" otherwise.
  `source setup_env.sh` (or `setup_env.csh`) from the bundle root sets `EDAUTILS_ROOT`,
  `EDAUTILS_LICENSE_FILE=$EDAUTILS_ROOT/edautils.lic` and prepends `bin/` to `PATH`.
- Standard packages: std/ieee/misc are read precompiled from `$EDAUTILS_ROOT/vhdl_pkgs/lib/...`,
  using `$EDAUTILS_ROOT/vhdl_pkgs/qtmap.ini` (`qtmap.win.ini` on Windows). With `-libset 2019` or
  `EDAUTILS_VHDL_LIBSET=2019`, the IEEE 1076-2019 set is used instead (`vhdl_pkgs/lib2019`, `qtmap2019.ini`).
- Licence: a valid licence file (none: exit status 10) and feature `VHDL_PARSER`. The feature is
  checked when the parser object is created. If it is missing, `Error: 6404: Failed to checkout LICENSE for the
  feature : VHDL_PARSER` is logged, the run is **not** stopped and the exit status stays 0. The file is searched in
  this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`.
- Optional environment: `JAVA_FLAGS` (passed to the JVM, e.g. `-Xmx8g`; with no heap option in it the launcher adds `-Xmx` sized to the machine (`bin/eu_heap.sh`: the largest of 64/32/16/12/8/4 GB within 3/4 of physical or cgroup memory, else 2 GB; `EDAUTILS_MAX_HEAP_GB` caps it)),
  `EDAUTILS_LOG_FILE` / `EDAUTILS_APPEND_LOG_FILE` (log file name; the second appends),
  `EDAUTILS_DISABLE_USAGE_TRACKING=true`, `EDAUTILS_PRINT_STACK_TRACE` (stack traces on
  internal exceptions), `EDAUTILS_ENABLE_DEBUG_ENVIRONMENT=1` (debug messages),
  `EDAUTILS_LIBRARY_MAP_FILE` (map file used when `-mapfile` is not given; default `qtmap.ini`),
  `EDAUTILS_VHDL_LIBSET`. `$EDAUTILS_ROOT` / `${EDAUTILS_ROOT}` in map-file paths are expanded.
- No external tools needed.

### Invocation

```
parsevhdl -compile|-analyze  -in <file.vhd> | -filelist <list>  [-work <lib>] [-mapfile <ini>] [options]
parsevhdl -load -du <primary>[:<secondary>]  [-work <lib>] [-mapfile <ini>] [-out <file>] [-elaborate] [options]
anvh      -in <file.vhd> | -filelist <list>  [-work <lib>] [-mapfile <ini>]
elabvh    -top|-du <entity>[:<arch>]  [-work <lib>] [-mapfile <ini>] [-out <file>] [-print_mra|-print_all_archs]
          [-toolprefix <name>] [-user <email>] [intent options]
```

Without intent options `elabvh` elaborates exactly as it always has and writes the top entity to
`-out`. The intent options -- `-upf`, `-upf_report`, `-sdc`, `-sdc_report`, `-annotate_upf`,
`-annotate_sdc`, `-upf_flatout`, `-sdc_flatout`, `-lint_upf`, `-lint_sdc`, `-lint_report` -- are the
ones `elabvl` takes, with the same behaviour, messages and exit codes (see the parseverilog
AGENTS.md, "Intent options"; report defaults `elabvh.*.rpt`): every UPF instance and hierarchical
pin must exist in the design (61010/61011), every SDC object query must match (61030), all reported,
exit 1; bound UPF objects carry `FVhPInstantiation`/`FVhPPort`/`FVhPSignal` in `actualObject`. With
`-annotate_upf`/`-annotate_sdc` the output holds every entity and architecture of the hierarchy,
children first, with the intent as `--` comments. A component instance is followed to the entity of
the same name (default binding) and its most recent architecture.

Options (shared parser `FVhPProcessCmdLineArgs`; all three launchers accept them):

| Option | Meaning |
|---|---|
| `-compile` / `-analyze` | Analyse the inputs into the work library (`parsevhdl`) |
| `-load` | Load `-du` from the library and decompile it into `-out` (`parsevhdl`) |
| `-elaborate` | Elaborate the loaded unit (`parsevhdl`; `elabvh` always elaborates) |
| `-du <p>[:<s>]` | Design unit: entity/configuration/package, optionally with `:architecture` or package body |
| `-top <name>` | Top entity (`elabvh` uses it when `-du` is absent) |
| `-in <file>` | VHDL input (wildcards resolved unless `-nowildcard`; several matches are written to `edautils.file.list`) |
| `-filelist <file>` | One file per line, optionally `lib=path` to analyse into `lib` (otherwise `work`) |
| `-work <lib>` | Logical work library (default `work`, with Warning 3530) |
| `-mapfile <ini>` | `logical=physical` map (default `qtmap.ini`); rewritten at the end with the work mappings |
| `-out <file>` | Decompiled output (default `decompiled.vhd`) |
| `-print_mra` / `-print_all_archs` | Also write `decompiled.<entity>.<arch>.vhd` for the most recent / every architecture |
| `-libset 2019` | Use the IEEE 1076-2019 std/ieee packages |
| `-stdpack` | Analyse as a standard package |
| `-printSrc` | Print source while analysing |
| `-inxml <f>` / `-inxmldesignunit <f>` / `-outxml <f>` / `-outxmldesignunit <du>` | XML restore/save of the design database (`parsevhdl`) |
| `-excludefilelist <f>`, `-nosort` | Accepted and stored. Not determined: this code path does not read them |
| `-l <log>` / `-la <log>` | Log file / append |
| `-quiet`, `-nobanner`, `-nowildcard`, `-suppress <id1:id2>`, `-user <email>` | As usual |
| `-ignore_metacomment <vendor> <directive>` (`*` = any) | Skip the code between matching `-- synopsys translate_off` / `translate_on` style fences (repeatable); without it the code is parsed and the object records its fences. Recognised vendors, directives and the Java API: see "Vendor meta comments" in the `parseverilog` AGENTS.md (same registry, `--` and `/* */` comments) |
| `-mark_metacomment <vendor> <directive>` (`*` = any) | Parse the code between matching fences and mark its objects with the region (repeatable; any vendor string; built-in vendors are marked anyway). `-ignore_metacomment` wins when both match. API: `FVhPDescription.registerMarkedRegion(vendor, directive)`, `registerIgnoredRegion(vendor, directive)`, `unregister...`/`clear...` (`addIgnoreMetaComment` is a deprecated alias) |
| `-print_metacomment` | Print the fences back around the architecture declarations and statements they enclosed (off by default) |
| `-help`, `-h` | Print usage and return |

Unrecognised options are **silently ignored** by `parsevhdl` and `anvh` (they are collected but never
reported); `elabvh` reports one as Error 61016 and exits 1 (it accepts `-toolprefix <name>` and
`-user <email>` as `elabvl` does). A value option given without its value throws an index exception, which is printed as an internal error.

### Inputs / Outputs

- Reads: VHDL sources, the map file if present, and the precompiled `vhdl_pkgs`.
- Writes: the work library directory (the path mapped for the work library; if unmapped, `./myEdaUtilsWork`),
  the map file (`qtmap.ini` by default, unless it is the precompiled one), `-out` (with `-load`),
  optional `decompiled.<entity>.<arch>.vhd`, `edautils.file.list` (wildcard `-in`), XML files.
- Log: `<prefix>.log` in the current directory (`ParseVHDL.log`, `anvh.log`, `elabvh.log`); override with
  `-l`/`-la` or `EDAUTILS_LOG_FILE`. Every console line is also written to the log.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (analysis errors, unit not found,
  `parsevhdl` without `-compile`/`-load` prints Error 4673 and returns 0; a missing `VHDL_PARSER` feature is
  only Error 6404). 10 = no valid licence file.
  1 = `anvh` without `-in`/`-filelist`, or `EDAUTILS_ROOT` missing/invalid; `elabvh` with an
  unrecognised option or a misused intent option, or with `-upf`/`-sdc` when the run reported any
  error. 2 = `elabvh -lint_upf/-lint_sdc` found lint errors (and nothing else failed).
- Message format: `<prefix>: <Severity>: <id>: <text>`, severity one of `Error`, `Fatal Error`,
  `Warning`, `Note`. `<id>` is a 5-digit message number. Usage lines have no severity or id.
- A completed run ends with `<prefix>: Note: <id>: Found N error(s) and M warning(s) ...`. Here it is
  printed **even with `-nobanner`**. It is missing when `parsevhdl` stops at Error 4673.

### Examples

Shipped: `examples/component_inst/` (`runme.csh`, `runme.bat`, `component_inst.vhd`, `qtmap.ini` = `work=./mywork`).
The script first creates `mywork/`:

```
cd $EDAUTILS_ROOT/examples/component_inst
mkdir -p mywork
parsevhdl -compile -mapfile ./qtmap.ini -work work -in component_inst.vhd
parsevhdl -load -work work -du component_inst -mapfile ./qtmap.ini -out decompiled.entity.vhd
parsevhdl -load -work work -du component_inst:rtl -mapfile ./qtmap.ini -out decompiled.architecture.vhd
```

Note: after its self-test, the release script deletes `examples/component_inst/qtmap.ini` and
`decompiled*.vhd` from the bundle. The run rewrites `qtmap.ini`, but if the file is missing, `work` maps to `./myEdaUtilsWork`.

From the regression suite (`tests.edautilscommandline/tests/vhdlparser/<case>/runme.csh` via
`../runme_common.csh`, with `../qtmap.ini` = `work=./mywork`):

```
parsevhdl -compile -mapfile ../qtmap.ini -work work -in <case>.vhd
parsevhdl -load -work work -du <case> -mapfile ../qtmap.ini -out decompiled.<case>.vhd
parsevhdl -help          # vhdlparser/help_msg, golden ParseVHDL.log.gld
```

`anvh` then `elabvh` runs in `tests/elab/vhdl_*` (no intent options), `tests/elabupf/vhdl_clean`
(`-upf`), `tests/elabsdc/vhdl_*` (`-sdc`), `tests/elabintent/vhdl_*` (annotation, flattened intent)
and `tests/elablint/*` (lint).

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Compile and load must share the same `-work` and `-mapfile`, and the run directory
  holds the library, the map file and the log. Give each parallel flow its own working directory.
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` **and** the `-out` file exists
  (the exit status alone does not reveal errors).

### See also

parseverilog, vhdl2verilog, vhdl2ipxact, genwrappervhdl; API docs in `doc/html/index.html`.
