# upgradeipxact

> Upgrade IP-XACT files between schema revisions (SPIRIT 1.4/1.5, IEEE 1685-2009, 2014, 2022).

- Catalog id: `Upgradeipxact`; bundle: `upgradeipxact`; latest version 20261018
- Documentation page: https://edautils.com/ip-xact.html
- Keywords: IP-XACT upgrade, IP-XACT 2009 to 2014, IP-XACT 2022, schema migration, IEEE 1685
- 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/upgradeipxact.md

## Downloads

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

Upgrades an IP-XACT XML file from an older revision to a newer one by running the Accellera
XSLT stylesheets shipped in `bin/xsl/`, one step at a time (e.g. 1.4 -> 1685-2009 -> 1685-2014
-> 1685-2022). Any document type the stylesheets handle can be upgraded (component, design, bus
and abstraction definition ...). Output is one XML file (default `output.xml`). Main class:
`com.eu.miscedautils.ipxactupdater.upgradeipxact` (jar `lib/upgradeipxact.jar`, with
`lib/xalan-2.7.3.jar`).

### Where it ships

Its own bundle, `upgradeipxact.tar.gz` (flow `upgradeipxact`; release tree
`release_scripts/upgradeipxact/1.0`), and as a point tool in the **ipxact-shell** and
**designplayer-shell** bundles (`bin/upgradeipxact` running the shell's jar; this guide as
`tools/upgradeipxact/AGENTS.md`, examples under `tools/upgradeipxact/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`, prepends `bin/` to `PATH` and sets
  `CLASSPATH=$EDAUTILS_ROOT/lib/upgradeipxact.jar` (the launcher sets its own `CLASSPATH`,
  xalan first).
- Stylesheets: `$EDAUTILS_ROOT/bin/xsl/from<A>_to_<B>.xsl` are **required**; the path is built
  from `EDAUTILS_ROOT`, not from the run directory. `bin/schemas` is not read.
- Xalan: the chain needs Xalan, not the JDK's built-in XSLTC (the stylesheets use the Xalan
  `node-set` extension). Xalan and its serializer are packed into `upgradeipxact.jar`, and
  `lib/xalan-2.7.3.jar` is shipped as well. The launcher passes
  `-Djdk.xml.xpathExprGrpLimit=5000 -Djdk.xml.xpathExprOpLimit=1100 -Djdk.xml.xpathTotalOpLimit=10010`
  (and `-Dcom.sun.management.jmxremote`); if you call `java` directly, pass the same flags or
  large stylesheets hit the JDK's XPath limits.
- Licence feature `UPGRADEIPXACT`. 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: Error
  "Failed to checkout LICENSE for the feature : UPGRADEIPXACT", 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 tool-specific environment variables are read.

### Invocation

```
upgradeipxact -in <file.xml> -from <version> [-to <version>] [-out <file.xml>]
              [-quiet] [-suppress <id1:id2>]
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT file to upgrade (mandatory) |
| `-from <ver>` | Revision of the input (mandatory): `1.0`, `1.1`, `1.2`, `1.4`, `1685_2009`, `1685_2014` (see the `1.5` note) |
| `-to <ver>` | Target revision (default **`1685_2014`**): `1.1`, `1.2`, `1.4`, `1.5`, `1685_2009`, `1685_2014`, `1685_2022` |
| `-out <file>` | Output file (default `output.xml`) |
| `-quiet` | Silence every message after the banner (log included); errors are then not counted |
| `-suppress <id1:id2>` | Colon-separated message numbers to suppress (non-numeric values throw an internal error) |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print usage and return |

Version names use underscores (`1685_2014`, not `1685-2014`). The step order is
1.0 -> 1.1 -> 1.2 -> 1.4 -> 1685_2009 -> 1685_2014 -> 1685_2022; `-to 1.5` takes the side branch
1.4 -> 1.5 (`from1.4_to_1.5.xsl`). Upgrading to 1685-2022 needs `-to 1685_2022` explicitly.

`-from` must be older than `-to`, otherwise Error "The version specified with the -from switch must
be lesser than the version specified with -to switch ..." (this includes `-from 1685_2022`).
An unknown value gives Error "Wrong IP-XACT version specified with the -from switch ..." (or
`-to`). **`-from 1.5` never works**, although the usage and the example comments list it: the code
only puts `1.5` in its version list when `-to 1.5`, where it then equals `-from`
(`from1.5_to_1685_2009.xsl` is shipped but unreachable). Workaround: none from this CLI.

There is no `-nobanner`. Any other word prints "Unrecognized option : <opt>" and the usage.
With no arguments, or without `-in` or `-from`, only the usage is printed (no error message).

### Inputs / Outputs

- Reads: the `-in` file and `$EDAUTILS_ROOT/bin/xsl/*.xsl`.
- Writes: `-out` (default `output.xml` in the current directory), indented by 4, **without an XML
  declaration**. For a multi-step upgrade each intermediate result is written to
  `<A>_to_<B>.xml` (e.g. `1685_2009_to_1685_2014.xml`) in the current directory and deleted when
  the JVM exits.
- Log: `upgradeipxact.log` in the current directory (override with `EDAUTILS_LOG_FILE`). Text the
  XSLT processor prints (stderr or stdout) is captured and logged as a Warning -- the stderr
  message is registered for error-to-warning downgrade -- so it does not count as an error.
- Upgrading only rewrites the XML; the result is not validated. Run validateipxact on it.

### Exit status and messages

- 0 on every normal return, **including failures** (bad version, failed transform, usage errors,
  internal exceptions). 10 = licence checkout failed. 1 = out of memory, or `EDAUTILS_ROOT`
  missing/invalid (launcher).
- Message format: `upgradeipxact: <Severity>: <id>: <text>`; `<id>` is a 5-digit number. Usage
  lines have no severity or id.
- A transform that returns nothing logs Error "Failed to convert from the version '<A>' to '<B>'
  version ..." and stops; an unwritable output logs "Failed to save converted outputs ...".
- The run ends with `upgradeipxact: Note: <id>: Found N error(s) and M warning(s) ...`.

### Examples

Shipped, each with `runme.csh` and `input.xml` (the two 2022 ones also carry the expected
`output.xml` and a `VERIFICATION.txt` describing how it was produced):

```
cd $EDAUTILS_ROOT/examples/1.4-to-1685_2009
upgradeipxact -in input.xml -from 1.4 -to 1685_2009
cd $EDAUTILS_ROOT/examples/1685_2009-to-1685_2022
upgradeipxact -in input.xml -from 1685_2009 -to 1685_2022
cd $EDAUTILS_ROOT/examples/1685_2014-to-1685_2022
upgradeipxact -in input.xml -from 1685_2014 -to 1685_2022
```

These `runme.csh` scripts give no `-out`, so the default `output.xml` **overwrites the shipped
reference `output.xml`** in the two 2022 examples. To compare, run with `-out new.xml` and
`diff new.xml output.xml`. `VERIFICATION.txt` records that the shipped `output.xml` files were
produced by running the same XSLT chain with Xalan directly, not through this CLI.

From the regression suite (reference: `tests.edautilscommandline/tests/upgradeipxact/test_2009_to_2014/runme.csh`
via `../runme_common.csh`; golden `output.xml.gld`):

```
upgradeipxact -in input.xml -out output.xml -from 1685_2009 -to 1685_2014
```

The family also has `test_1_4_to_2014` and `unwanted_expr_1_4_to_2014`; `test_1_4_to_1_5` and
`test_1_4_to_2009` exist but the family's `runme.csh` skips them (the reason is not recorded).

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, the default output and the intermediate `<A>_to_<B>.xml` 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 **and** the log contains `Found 0 error(s)` (do not use `-quiet` if
  you rely on it) **and** the `-out` file exists. Delete a stale `-out` first.

### See also

validateipxact, compareipxact, ipxact-shell.
