# ipxact2tcl

> Turn an IP-XACT 1685-2009 component into the ipxact-shell Tcl commands that rebuild it, so the component can be edited and regenerated as a script.

- Catalog id: `Ipxact2tcl`; bundle: `ipxact2tcl`; latest version 20261018
- Keywords: IP-XACT to Tcl, IP-XACT component script, 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/ipxact2tcl.md

## Downloads

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

Reads one IP-XACT 1685-2009 component XML and writes the equivalent ipxact-shell Tcl commands,
so the component can be rebuilt (or edited) as a script instead of XML. Output is one Tcl file
(default `component.command.tcl`) that is meant to be run with `ipxact-shell -f <file>`.
IP-XACT 1685-2014 input is rejected. Main class: `com.eu.miscedautils.shell.ipxact2tcl`
(jar `lib/designplayer.jar`).

### Where it ships

Its own bundle, `ipxact2tcl.tar.gz` (flow `ipxact2tcl`; release tree
`release_scripts/ipxact2tcl/1.0`), and as a point tool in the **ipxact-shell** and
**designplayer-shell** bundles (`bin/ipxact2tcl` running the shell's jar; this guide as
`tools/ipxact2tcl/AGENTS.md`, examples under `tools/ipxact2tcl/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/`).
  **This launcher does not check it**: unlike the other launchers it has no
  "Environment variable EDAUTILS_ROOT is not set" guard, so an unset `EDAUTILS_ROOT` shows up
  as a Java "could not find or load main class" error (classpath `/lib/designplayer.jar`).
  `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 `IPXACT2TCL`. 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.
  (`README.txt` still says `EDAUTILS_LICENSE_KEY`; that variable is not read.)
- 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).
  `EDAUTILS_IPXACT_SEARCH_PATH` (colon-separated directories): when set, the IP-XACT 2009
  loader loads every IP-XACT file found there on first use, before the `-in` file.
- No external tools needed to generate; running the result needs `ipxact-shell`.

### Invocation

```
ipxact2tcl -in <component.xml> [-out <file.tcl>] [-nobanner] [-quiet] [-suppress <id1:id2>]
```

| Option | Meaning |
|---|---|
| `-in <file>` | IP-XACT 1685-2009 component XML (effectively mandatory) |
| `-out <file>` | Output Tcl file (default `component.command.tcl`; parent dirs are not created) |
| `-nobanner` | No banner, and no completion summary |
| `-quiet` | Silence every later message (log included); errors are then not counted |
| `-suppress <id1:id2>` | Colon-separated message numbers to suppress |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print the one-line usage and exit |

Parsing quirk: once `-in` has been seen, any token that is not one of the options above is
silently accepted as an extra input file and ignored (only the last `-in` file is converted).
That includes `-help` placed after `-in`. Before `-in`, an unknown option prints
"Unrecognized option : <opt>" and the usage. No arguments at all prints the usage.

### Inputs / Outputs

- Reads: the `-in` component XML. A 1685-2014 component gives the error
  "IP-XACT 2014 is not supported in the ipxact2tcl conversion ..."; handling of 1685-2022
  input was not determined from the code read.
- Writes: `-out` file (default `component.command.tcl` in the current directory).
- Log: `ipxact2tcl.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 every normal return, **including failures** (unreadable input, 2014 input, write
  failure). 10 = licence checkout failed.
- Message format: `ipxact2tcl: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit message number. Usage lines and the
  "Run it as: ipxact-shell -f <file>" line have no severity or id.
- Success prints `Note: ...: Created Tcl command file <out> ... ` then
  `Found N error(s) and M warning(s) ...` (not with `-nobanner`).
- **On failure the tool returns early without the `Found N error(s)` summary**: a missing
  `-in` gives only the warning "NULL object passed as ipxact file to load Component XML ...",
  an unreadable file gives "Can not read given file <f>".

### Examples

Shipped: `examples/simpletest_with_generics/` (`runme.csh`, `runme.bat`,
`simpletest_with_param.xml`, a 1685-2009 component):

```
cd $EDAUTILS_ROOT/examples/simpletest_with_generics
ipxact2tcl -in simpletest_with_param.xml -out simpletest_with_param.tcl
```

From the regression suite (reference: `tests.edautilscommandline/tests/ipxact2tcl/i2c/runme.csh`),
round trip back to XML through ipxact-shell:

```
ipxact2tcl -in i2c.generated.xml.gld            # writes component.command.tcl
ipxact-shell -v2009 -f component.command.tcl
```

Help golden: `tests.edautilscommandline/tests/ipxact2tcl/help_msg/runme.csh` (`ipxact2tcl -help`).

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and default output into the current directory: give each parallel run its
  own working directory (or distinct `-out` and `EDAUTILS_LOG_FILE`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Created Tcl command file` and
  `Found 0 error(s)` (do not use `-nobanner` or `-quiet` if you rely on these) **and** the
  `-out` file exists and is non-empty. Exit status alone never signals failure.
- Windows: `bin/ipxact2tcl.bat` does not set `CLASSPATH`; it relies on `setup_env.bat`.

### See also

ipxact-shell, ipxact2verilog, ipxact2vhdlentity, upgradeipxact (older SPIRIT versions up to
1685-2009), validateipxact.
