# compareipxact

> Compare two IP-XACT components or designs and report every difference in ports, parameters, bus interfaces, memory maps and registers.

- Catalog id: `Compareipxact`; bundle: `compareipxact`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: IP-XACT compare, IP-XACT diff, IEEE 1685, component comparison
- 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/compareipxact.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Compareipxact (latest file `compareipxact-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/ip-xact-tools/files/compareipxact/
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/compareipxact/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/compareipxact-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 two IP-XACT XML files of the same document type (component, bus definition,
abstraction definition, ...) with EMF Compare. The models are built from the XSD schemas
shipped in `bin/schemas/` (IP-XACT 1685-2014), or from a schema given with `-xsd`. Output is a
numbered difference list written to a text file (default `diff.txt`) and echoed to the log.
Main class: `com.eu.miscedautils.compareipxact.compareipxact` (jar `lib/designplayer.jar`).

### Where it ships

Its own bundle, `compareipxact.tar.gz` (flow `compareipxact`; release tree
`release_scripts/compareipxact/1.0`), and as a point tool in the **ipxact-shell**, **baya-shell**
and **designplayer-shell** bundles (`bin/compareipxact` running the shell's jar; this guide as
`tools/compareipxact/AGENTS.md`, examples under `tools/compareipxact/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`.
- Schemas: `$EDAUTILS_ROOT/bin/schemas/*.xsd` (flat, namespace
  `http://www.accellera.org/XMLSchema/IPXACT/1685-2014`). Required unless `-xsd` is given.
- Licence feature `COMPAREIPXACT`. The licence file is searched in this order:
  `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`. No licence for the feature: 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).
  The `EDAUTILS_IPXACT_SEARCH_PATH*` variables are not read by this tool.
- No external tools needed.

### Invocation

```
compareipxact -golden <file.xml> -revised <file.xml>  <type switch> | -xsd <schema.xsd>
              [-outfile <file>] [-v2009|-v2014|-v2022] [-origin <file.xml>] [-user <email>]
```

| Option | Meaning |
|---|---|
| `-golden <file>` | Golden IP-XACT file (mandatory) |
| `-revised <file>` | Revised IP-XACT file (mandatory) |
| `-component`, `-busdefinition`, `-abstractiondefinition`, `-abstractor`, `-design`, `-catalog`, `-designcfg` | Document type; selects `bin/schemas/<type>.xsd` (one of these or `-xsd` is mandatory) |
| `-generator` | Documented as "IP-XACT Generator", but the code maps it to the design-configuration type (`designConfig.xsd`), same as `-designcfg` |
| `-xsd <schema>` | Schema file to use instead of a type switch (it wins over the type switch) |
| `-outfile <file>` | Difference report (default `diff.txt`) |
| `-v2009`, `-v2014`, `-v2022` | Use `bin/schemas/1685-<year>/<type>.xsd`. **This bundle ships no such sub-directory**, so these switches end in Error "IP-XACT 1685-<year> schemas are not installed" unless used with `-xsd` |
| `-origin <file>` | Origin for a 3-way comparison. Broken: the code creates the origin resource from the revised file's URI without loading it, which throws; the run reports an internal exception and exits 1 |
| `-user <email>` | User id for usage registration |

There is no `-help`, `-nobanner` or `-quiet`: any unknown word (including `-help`) gives
Error "Unrecognized option : <opt>", the usage, and exit 1. Missing golden/revised/type:
Error "Missing mandatory input(s) ...", the usage, exit 1. The banner is always printed.

### Inputs / Outputs

- Reads: the golden and revised XML files and the schema. Each XML is first copied, with its
  `schemaLocation` stripped, to a temporary `edautils*.xml` in `java.io.tmpdir` (or `.` if that
  is not writable), deleted when the JVM exits.
- Writes: the `-outfile` report, one line per difference, e.g.
  `[  1] Attribute change : vendor : spiritconsortium.org -> spiritconsortium.org2`
  (golden value -> revised value). **When the files are equivalent no report file is
  written**; the log says "Files are equivalent - no diffrenece found".
- Log: `compareipxact.log` in the current directory (override with `EDAUTILS_LOG_FILE`).
  The differences are echoed between `******************Differences ***` markers.

### Exit status and messages

- 0 on a normal finish (also after in-run errors such as an unreadable input file or missing
  schema, which are reported but not fatal). 1 = unrecognised option, missing mandatory
  input, or an internal exception. 10 = licence checkout failed. 1 also = `EDAUTILS_ROOT`
  missing/invalid (launcher).
- Message format: `compareipxact: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`, `Programming Error`; `<id>` is a 5-digit message number.
  Key notes: `Found total differences : N`, `Written differences into file : <f>`.
- The run ends with `compareipxact: Note: <id>: Found N error(s) and M warning(s) ...`.

### Examples

Shipped: `examples/i2c/`, `examples/busdefinition/` (with its own `busdef.xsd` and
`identifier.xsd`), `examples/abstractiondefinition/`, each with `runme.csh`:

```
cd $EDAUTILS_ROOT/examples/i2c
compareipxact -revised i2c.xml -golden i2c.modified.xml -component -outfile Diff.rpt
cd $EDAUTILS_ROOT/examples/busdefinition
compareipxact -revised clock.modified.xml -golden clock.xml -xsd busdef.xsd -outfile Diff.rpt
```

From the regression suite (reference:
`tests.edautilscommandline/tests/compareipxact/busdefinition/runme.csh`):

```
compareipxact -busdefinition -revised clock.modified.xml -golden clock.xml -outfile Diff.rpt
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and the default report into the current directory: give each parallel run
  its own working directory (or distinct `-outfile` and `EDAUTILS_LOG_FILE`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)`. Then either
  `Files are equivalent` (no report file) or `Found total differences : N` (report written).
  Delete a stale `-outfile` before the run, since an equivalent pair leaves it untouched.

### See also

validateipxact, upgradeipxact, ipxact-shell.
