# uniquifyverilog

> Uniquify Verilog modules, classes, structures, interfaces and packages

- Catalog id: `Uniquifyverilog`; bundle: `uniquifyverilog`; latest version 20261018
- Documentation page: https://edautils.com/RTLUtils.html
- Keywords: uniquify Verilog, unique module names, SystemVerilog uniquify, parameterized module
- 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/uniquifyverilog.md

## Downloads

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

Surgically renames the declarations in Verilog/SystemVerilog source -- modules, interfaces,
packages, classes and struct/union typedef names -- to `<prefix>_<name>` and follows each rename
through its references (instantiations, imports, port types), so that one copy of a design can
sit beside another without name clashes. With `-vhdl` it does the same for VHDL design units.
Only files that change are written, into an output directory (default `outputs_uniquified/`),
with the rest of the text kept as written. Main class:
`com.eu.miscedautils.surgicalchange.UniquifyVerilog` (jar
`lib/surgicalchange.jar`). The bundle has two launchers onto the same class:
`bin/uniquifyverilog` and `bin/uniquifymodules` (the name used by the `rtluniquifier` tests).
Before release 10.0 (October 2026) the package was `com.eu.miscedautils.verilogsurgicalchange` and the
jar `lib/verilogsurgicalchange.jar`; a script that names either directly must use the new names.

### Where it ships

Its own bundle, `uniquifyverilog.tar.gz` (flow `uniquifyverilog`; release tree
`release_scripts/uniquifyverilog/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/uniquifymodules`, `bin/uniquifyverilog` running the shell's jar; this guide as
`tools/uniquifyverilog/AGENTS.md`, examples under `tools/uniquifyverilog/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`.
- Licence: a valid licence file is required at start-up (else exit status 10, no message).
  The licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic`
  (run directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. The Verilog renamers
  check feature `UNIQUIFYVERILOG`; a missing feature is error 56404
  `Failed to checkout LICENSE for the feature : UNIQUIFYVERILOG`; the run continues and exits 1.
  From source, the `-vhdl` path checks no feature.
- 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).
- On Unix the default Verilog path restores preprocessor text with `diff` and `patch` run from a
  generated `./patchscript.sh` (`/bin/sh`), so both must be on `PATH` and the current directory
  must be writable and allow executing that script. `-vhdl` and
  `-uniquify_parser_object_model` do not use them.

### Invocation

```
uniquifyverilog -in <file.v> | -f <filelist>  [-prefix <prefix>]  [-outdir <dir> | -out <file>]
                [-nouniquify <types>] [-vhdl] [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-prefix <p>` | Prefix; names become `<p>_<name>` (default `edautils`) |
| `-outdir <dir>` | Directory for rewritten files (default `outputs_uniquified`) |
| `-out <file>` | Write the single result here instead of `<outdir>/<basename>`. Verilog: only with `-in` and no `-f`, else warning 56817. `-vhdl`: only with exactly one input file, else warning 56818. In both cases `-outdir` is then used |
| `-nouniquify <t1:t2>` | Do not rename these kinds: `module`, `interface`, `class`, `structure`, `package` (unknown kind = error 55630) |
| `-vhdl` | Inputs are VHDL: rename entity, package, package body, component and configuration names and their references, unqualified or `work.`-qualified (`entity work.x`, `configuration work.c`, `use work.pkg.all`); library names and references qualified by any other library are left alone; case is preserved. See "VHDL" below |
| `-verilog` | Accepted and ignored (Verilog is the default) |
| `-uniquify_parser_object_model` | Alternative engine: parse into the full object model, then save uniquified files into `-outdir` (`-out`, `-no_pp`, `-print_parse_errors` are not used) |
| `-replace_path_sep` | Name each output after the input's full path with separators replaced, not its basename |
| `-no_pp` | Skip Verilog preprocessing (only if the input has no compiler directives) |
| `-print_parse_errors` | Enable printing of parse errors (per the usage text; use it if the result is unexpected) |
| `-top <module>` | The top module keeps its name: its declaration and `endmodule` label are not renamed (both Verilog engines; the default engine also leaves instantiations of it alone). Not used by `-vhdl` |
| `-help`, `-h` | Print usage and return |

The usage text omits `-vhdl` and says the flow reads Verilog only; the code accepts `-vhdl`. An
unknown option is error 56816 "Unknown option" followed by the usage, exit 255.

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`): `-in <file>`,
`-f <filelist>` (repeatable; one file per line, `#`/`// ` comments, `+incdir+`/`+define+` and
option lines allowed, `$VAR` resolved), `-excludefilelist <file>`, `+incdir+<p1>+<p2>`,
`+define+A+B=1`, `-v95`, `-nowildcard`, `-nokeywords a:b`, `-l <log>` / `-la <log>`, `-quiet`,
`-nobanner` (has no effect here), `-dbg` (also keeps `patchscript.sh` and temp files),
`-suppress <id1:id2>`, `-user <email>`.

### What is renamed

- Verilog (default engine): every module, interface, package, class and struct/union typedef
  declared in the input, except the `-top` module and kinds excluded by `-nouniquify`. An
  instantiation is renamed only when its master (module, interface, class or struct/union
  typedef) is declared somewhere in the run's input set and its kind is not excluded; an
  undeclared master, such as a library cell or a module from outside the input, keeps its name.
  Named gate primitives (`and g1(...)`) are left alone. A lexing pre-pass collects the declared
  names, so each input is read twice.
- VHDL (`-vhdl`): a component (declaration, configuration specification, instantiation) is
  renamed only when an entity of that name is declared in the input set, so a vendor or library
  component keeps its name and default binding. A pre-pass parses every input to collect the
  entity names, so each input is read twice. Known limitation: `use entity work.X(rtl)` inside a
  binding indication (`for ... : comp use entity work.X(rtl)`) is not renamed; fix it by hand.

### Inputs / Outputs

- Reads: the Verilog (or, with `-vhdl`, VHDL) files from `-in` / `-f`, and `` `include`` files.
  Each file is rewritten on its own; references are renamed by name, so give all files that
  must stay consistent the same `-prefix` (and the same run, so the declared-name sets match).
- Writes: `<outdir>/<basename>` (or the `-out` file) for every input file that changed
  (Note 57826 "Saved modified contents file"); files with nothing to rename are not written
  (Note 55384 "Nothing changed in the file").
- Log: `uniquifyverilog.log` in the current directory, for both launchers. Also created there:
  `myEdaUtilsWork/`, `edautils_temp/`, temporary `edautils_temp_file*` files and
  `patchscript.sh` (removed at the end unless `-dbg`).

### Exit status and messages

- 0 when the run finished with no error. 1 = the run reported any error (parse errors, unknown
  `-nouniquify` kind, licence feature missing ...) or caught an internal exception,
  `EDAUTILS_ROOT` missing, or out of memory (Fatal Error 53092). 255 = unknown option, missing
  input (error 54026), or `-vhdl` with no input file (54028). 10 = no valid licence file.
- Message format: `uniquifyverilog: <Severity>: <id>: <text>`; the printed id is 50000 + the
  source number, and `-suppress` takes the printed id. The banner is always printed.
- The run ends with `uniquifyverilog: Note: 53250: Found N error(s) and M warning(s) ...`
  (not on the exit-255 paths).
- Per the ledger (2026-09-25), before that date the default Verilog engine discarded every
  rename ("Nothing changed" on every file, no output) and `-vhdl` did not exist; an older
  bundle behaves that way.

### Examples

Shipped: `examples/simple_macro/` (`runme.csh`, `simple_macro.v`):

```
cd $EDAUTILS_ROOT/examples/simple_macro
uniquifyverilog -in simple_macro.v -prefix foo
```

This writes `outputs_uniquified/simple_macro.v` with `foo_leaf` and `foo_module_instance`, the
`` `ifdef``/`` `define`` block kept as written. The bundle self-test (`uniquifyverilog_example`)
runs it with `</dev/null` and requires `Found 0 error(s)` in `uniquifyverilog.log`.

From the regression suite (references: `tests.edautilscommandline/tests/uniquifyverilog/cpu8080`
via `../runme_common.csh`, and `tests/rtluniquifier/uniquify_modules` and `vhdlonly`):

```
uniquifyverilog -f infile.list -prefix cpu800 -top cpu800
uniquifymodules -verilog -in design.v -prefix blockA -out design.pfx.v
uniquifymodules -vhdl -in test1.vhd -out uniquified_test1.vhd
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `outputs_uniquified/`, `patchscript.sh` and temp files 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 (the log then says `Found 0 error(s)`) **and** the expected
  output file exists (its absence means nothing in that file was renamed).

### See also

punchports and swapcells (same surgical-edit engine), createhierarchy, preprocessverilog.
