# mergemodules

> Pull instances from different modules to build new module, maximizing reuse

- Catalog id: `Mergemodules`; bundle: `mergemodules`; latest version 20261018
- Documentation page: https://edautils.com/Baya.html
- Keywords: merge modules, Verilog reuse, module builder, RTL restructuring
- 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/mergemodules.md

## Downloads

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

Merges the results of grouping runs that were done in parallel on the same design. Each input
file is parsed on its own, in input order; after each file the module named by `-top` (and any
module named with `inst@module` in `-instances`) is looked up and the named instances in it are
recorded, then those modules are dropped so a later file may define the same module name again.
One recorded instance's module is the destination (`-start_instance`); every other recorded
instance is moved into it: the leaf instances that the moved instance groups (its master's
sub-instances) are found by name at the top level of the destination, removed, and replaced by
the moved instance, whose pins are reconnected to the nets the removed instances used. Output is
a single Verilog file (default `output.v`) holding only the merged destination module. Main
class: `com.eu.miscedautils.shell.MergeModules` (jar `lib/designplayer.jar`).

### Where it ships

Its own bundle, `mergemodules.tar.gz` (flow `mergemodules`; release tree
`release_scripts/mergemodules/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/mergemodules` running the shell's jar; this guide as `tools/mergemodules/AGENTS.md`,
examples under `tools/mergemodules/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 feature `MERGEMODULES`. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`. No valid licence file: exit status 10, no message. Valid file
  without the feature: error 56404 `Failed to checkout LICENSE for the feature : MERGEMODULES`,
  the summary line, then exit status 10.
- 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

```
mergemodules -f <filelist> | -in <file.v>  -top <module>  -instances <i1[@mod]:i2[@mod]:...>
             [-start_instance <inst[@mod]>]  [-out <file>]  [options]
```

Tool-specific options:

| Option | Meaning |
|---|---|
| `-top <module>` | Module holding the instances (mandatory; missing = error 51285) |
| `-instances <list>` | Colon-separated instances to merge (mandatory; missing = error 51286). `inst@module` looks the instance up in `module` instead of `-top` |
| `-start_instance <inst[@mod]>` | Instance whose module is the destination; only the part before `@` is matched |
| `-out <file>` | Output Verilog file (default `output.v`; parent dirs created) |
| `-noreparse` | Accepted for compatibility and ignored |
| `-help`, `-h` | Print usage and return |

Without `-start_instance` the destination is whichever recorded module a Java `HashMap`
iterates first, which is not the input order: always pass `-start_instance`. At least two
distinct modules must be recorded, else error 50313 "At least two modules are required to
combine ..." (none at all is error 50312). A connection that carries a bit range is not merged:
error 55932 "Range is not yet supported while surgical merging of modules".

Common Verilog-reader options (shared parser, `FVPProcessCmdLineArgs`): `-in <file>` (wildcards
expanded unless `-nowildcard`; each matching file is parsed separately), `-f <filelist>`
(repeatable; one file per line, `#`/`// ` comments, option lines allowed, `$VAR` resolved),
`-excludefilelist <file>`, `-v95`, `-nowildcard`, `-l <log>` / `-la <log>` (log file /
append), `-quiet`, `-nobanner`, `-suppress <id1:id2>`, `-user <email>`. `+incdir+` and
`+define+` are parsed but, from source, the per-file parse is given an empty include list, so a
command-line `+incdir+` does not reach it; whether `+define+` does is not confirmed.
Anything else is error 51287 "Illegal option" (or 51288 for a bare value) followed by the usage;
the name printed in that message can be the wrong argument (the code indexes the original
argument array with the leftover-argument index).

### Inputs / Outputs

- Reads: the Verilog files from `-f` / `-in` and their `` `include`` files. The file order
  matters only for which definition of a repeated module is seen when it is looked up.
- Writes: the `-out` file (default `output.v`), a copyright header followed by the merged
  destination module only (not its sub-modules). No file is written when nothing was merged
  (error 51337 "Merged module not found ...").
- Log: `mergemodules.log` in the current directory (override with `-l`/`-la` or
  `EDAUTILS_LOG_FILE`). `myEdaUtilsWork/` is created in the current directory.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing mandatory options,
  fewer than two modules, illegal options). 10 = licence problem (see Prerequisites).
  1 = `EDAUTILS_ROOT` missing, or out of memory (Fatal Error 53092, JVM halted).
- Message format: `mergemodules: <Severity>: <id>: <text>`; the printed id is 50000 + the
  source number, and `-suppress` takes the printed id. Usage lines have no severity or id.
- The run ends with `mergemodules: Note: 53250: Found N error(s) and M warning(s) ...`. This
  summary is **not printed with `-nobanner`**, nor when the usage is printed for an illegal option.
- The ledger (2026-09-07) records one benign warning 56271 "Method getConstituentNetList() is
  not yet implemented for the expression of type : 'INTEGERBINARY'" on the `simple_and_3`
  design; the merged output is still correct.

### Examples

Shipped: `examples/simple_and_3/` (`runme.csh`, `infile.list`, `top1.v`, `top2.v`,
`bottom1.v`, `bottom2.v`). `top1.v` groups `u_t1_bot` into `u_tile1` inside `simple_and_3`;
`top2.v` groups `u_t2_bot` into `u_tile2` inside `simple_and_xxx`. The merge moves `u_tile1`
into `simple_and_xxx` in place of its top-level `u_t1_bot`:

```
cd $EDAUTILS_ROOT/examples/simple_and_3
mergemodules -f infile.list -top simple_and_3 -out output.v \
    -instances u_tile1:u_tile2@simple_and_xxx -start_instance u_tile2@simple_and_xxx
```

The bundle self-test (`bundle_jar_files.csh`, `mergemodules_example`) runs that `runme.csh`
with `</dev/null` and requires `Found 0 error(s)` in `mergemodules.log`.

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

```
mergemodules -f infile.list -top simple_and_3 -out output.v \
    -instances u_HM1:u_HM2@simple_and_xxx -start_instance u_HM2@simple_and_xxx -suppress 56268
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, default output and `myEdaUtilsWork/` into the current directory: give each
  parallel run its own working directory (or distinct `-out` and `-l`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` (do not use
  `-nobanner` if you rely on that line) **and** the `-out` file exists.

### See also

createhierarchy (produces the grouped hierarchies this tool merges), removehierarchy,
flatteninstances, parseverilog.
