# compareentities

> Compare VHDL Entities for port/generics changes between versions

- Catalog id: `Compareentities`; bundle: `compareentities`; latest version 20261018
- Documentation page: https://edautils.com/Baya.html
- Keywords: VHDL entity compare, port comparison, generics comparison, VHDL diff
- 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/compareentities.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Compareentities (latest file `compareentities-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/compareentities/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/compareentities-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.

Compares the interface of two revisions of a VHDL entity: a golden and a revised VHDL source
(single file or file list) are parsed, the entity named by `-top` (or `-goldenTop` /
`-revisedTop`) is found in each, and differences in generics and ports (optionally also the
component instances of the most recently compiled architecture) are written as a text table
(default `diff.txt`) and a CSV file (default `diff.csv`). Main class:
`com.eu.miscedautils.modulecomparator.vhdl.CompareEntities` (jar `lib/modulecomparator.jar`).

### Where it ships

Its own bundle, `compareentities.tar.gz` (flow `compareentities`; release tree
`release_scripts/compareentities/1.0`), and as a point tool in the **baya-shell** and
**designplayer-shell** bundles (`bin/compareentities` running the shell's jar; this guide as
`tools/compareentities/AGENTS.md`, examples under `tools/compareentities/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`, `CLASSPATH` and prepends `bin/` to `PATH`.
- VHDL standard packages: the parser reads `$EDAUTILS_ROOT/vhdl_pkgs/qtmap.ini`
  (`qtmap.win.ini` on Windows) for the precompiled standard libraries. `vhdl_pkgs/` is not in
  the source tree of this bundle; the release build (`bundle_jar_files.csh`, `need_vhdl_pkgs`)
  copies it in from parsevhdl. Missing -> "Failed to read VHDL precompiled library map file".
- Licence: a valid licence file is required (else exit status 10), plus feature
  `VHDLENTITYCOMPARE`, checked by the comparator; a missing feature prints the licence
  checkout failure but the run still exits 0. The licence 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).
- No external tools needed.

### Invocation

```
compareentities -goldenFile <g.vhd> -revisedFile <r.vhd> | -goldenFileList <g.f> -revisedFileList <r.f>
                -top <entity> | -goldenTop <entity> -revisedTop <entity>  [options]
```

| Option | Meaning |
|---|---|
| `-goldenFile <file>` / `-revisedFile <file>` | Golden / revised VHDL file |
| `-goldenFileList <f>` / `-revisedFileList <f>` | File lists: one file per line, optionally `lib=file` (default library `work`) |
| `-top <entity>` | Entity name in both revisions (overrides `-goldenTop`/`-revisedTop`) |
| `-goldenTop <e>` / `-revisedTop <e>` | Entity names when they differ |
| `-outtxt <file>` | Text report (default `diff.txt`) |
| `-outcsv <file>` | CSV report (default `diff.csv`) |
| `-compare_instances` | Also compare instances in the most recently compiled architecture |
| `-work <lib>` | Work library for both revisions (default `work`) |
| `-goldenWork <lib>` / `-revisedWork <lib>` | Per-revision work library |
| `-mapfile <ini>` | Logical=physical library map (default `qtmap.ini`; read if present, rewritten at the end) |
| `-analyze` | Analyse mode; requires a single-file input |
| `-quiet` | Do not print log messages to the console |
| `-suppress <id1:id2>` | Suppress messages with these numbers |
| `-user <email>` | User id for usage registration |
| `-nobanner`, `-sort`, `-nowildcard`, `-excludefilelist <f>` | Accepted, but have no effect (the banner is always printed) |

A file and a file list for the same revision cannot be mixed. Missing top or inputs:
Error "Missing mandatory input ..." then the usage. An unrecognised option (or no argument)
prints the usage **without** an error message and exits. There is no `-help` option as such;
any unknown word, including `-help`, prints the usage. The usage text does not list
`-quiet`, `-suppress`, `-user`, `-nobanner`. Options are case-sensitive except `-analyze`,
`-mapfile`, `-work`, `-goldenWork`, `-revisedWork`, `-quiet`, `-nobanner`.

### Inputs / Outputs

- Reads: the golden and revised VHDL files / lists, `$EDAUTILS_ROOT/vhdl_pkgs`, and the
  `-mapfile` if it exists.
- Writes: `-outtxt` and `-outcsv` reports; the work library directory (default
  `myEdaUtilsWork/`) and the map file (`qtmap.ini`) in the current directory.
- Report rows: golden value, revised value, comment (e.g. `Type mismatch for port : in1`);
  the CSV header is `Golden <entity>,Revised <entity>,Comments`.
- Log: `CompareEntities.log` in the current directory (override with `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** (missing options, entity not
  found, parse errors, missing licence feature all return 0). 10 = no valid licence.
  1 = `EDAUTILS_ROOT` missing/invalid.
- Message format: `CompareEntities: <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. The count is logged as
  `Completed comparison, total number of differences : N`.
- The run ends with `CompareEntities: Note: <id>: Found N error(s) and M warning(s) ...`
  (printed also when the top entity is not found; not affected by `-nobanner`).

### Examples

Shipped: `examples/simple_array_2d_2/` (`runme.csh`, `simple_array_2d_2.golden.vhd`,
`simple_array_2d_2.revised.vhd`):

```
cd $EDAUTILS_ROOT/examples/simple_array_2d_2
compareentities -goldenFile simple_array_2d_2.golden.vhd -revisedFile simple_array_2d_2.revised.vhd \
    -top simple_array_2d_2 -outcsv output.diff.csv -outtxt output.diff.txt
```

From the regression suite (reference:
`tests.edautilscommandline/tests/compareentities/component_inst/runme.csh` via
`../runme_common.csh`):

```
compareentities -goldenFile component_inst.golden.vhd -revisedFile component_inst.revised.vhd \
    -top component_inst -outcsv output.diff.csv -outtxt output.diff.txt \
    -mapfile qtmap.ini -goldenWork goldenwork -revisedWork revisedWork -compare_instances
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, reports, `qtmap.ini` and the work directory into the current directory:
  give each parallel run 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** both report
  files exist. The exit status never signals "entities differ"; read the reports or the
  `total number of differences` line.

### See also

comparemoduleinterfaces (Verilog counterpart), parsevhdl, vhdl2ipxact.
