# sdc-shell

> SDC constraints parser and Tcl shell: load, query, edit and write back Synopsys Design Constraints (create_clock, set_input_delay, get_ports ...) with a Tcl API.

- Catalog id: `SdcShell`; bundle: `sdc-shell`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: SDC parser, Synopsys Design Constraints, timing constraints, Tcl shell, constraint editor
- 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/sdc-shell.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/SdcShell (latest file `sdc-shell-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/parsers-liberty-upf-sdc-vcd/files/sdc-shell/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/sdc-shell-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.

The SDC (Synopsys Design Constraints) Tcl shell: executes SDC files as Tcl scripts into a
constraints data model you can query, plus the SDC point tools (compare, parse, lint). `README.txt` in this
directory is out of date (it describes the UPF shell and `upf-shell -f foo.upf`); this file is
the agent's reference.

All paths below are relative to the bundle root (the directory holding this file).

### Prerequisites

- `java` on `PATH`. 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`. `bin/sdc-shell` runs
  plain `java` with `$JAVA_FLAGS` (e.g. `JAVA_FLAGS=" -Xmx4g "`; unset or without a heap option, the launcher adds `-Xmx` sized to the machine, see `bin/eu_heap.sh`; the
  regression suite uses `-Xms512m -Xmx2048m`). There is no `sdc-shell.bat`; on Windows only the
  point tools' `.bat` launchers are shipped.
- `EDAUTILS_ROOT` = this bundle root. Every launcher in `bin/` exits 1 with
  "Environment variable EDAUTILS_ROOT is not set" otherwise. All of them run `lib/sdc.jar`.
- A licence carrying feature `SDCBACKBONE`. The bundle ships `edautils.lic`, a time-limited
  evaluation licence issued when the bundle was built. The tool looks for a licence in this
  order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory), `$HOME/edautils.lic`,
  `$EDAUTILS_ROOT/edautils.lic`. It must carry this release's content key, or the protected
  Tcl layer in `bin/tcl` cannot be decrypted (exit 11, see below).
- Protected Tcl layer: `bin/tcl/*.tcl.encrypted` plus the signed `edautils.manifest` (the
  release build copies them from designplayer-shell). Do not add, remove or edit files there.
- Optional: `EDAUTILS_DISABLE_USAGE_TRACKING=1` (or `true`) stops the tool opening its
  usage-report mail connection -- set it in sandboxes and offline runs.
  `EDAUTILS_DISABLE_AUTO_EMAILS_TO_EDAUTILS=1` has the same effect.
- Optional: `EDAUTILS_TCL_ENABLE_SPACE_CHECK_IN_MULTILINE_CMD=1` makes the shell repair a
  script whose continuation lines have blanks after the trailing `\` (Warning 2200; it runs a
  `<file>.tmp.edautils` copy, deleted at exit).
- Optional: `EDAUTILS_LOG_FILE` / `EDAUTILS_APPEND_LOG_FILE` (log file name; the second
  appends), `EDAUTILS_PRINT_STACK_TRACE` (stack traces on internal exceptions).

Environment set-up, equivalent to `setup_env.sh` / `setup_env.csh` / `setup_env.bat`
(which must be sourced from the bundle root -- they use the current directory):

```sh
export EDAUTILS_ROOT=/path/to/sdc-shell/<DATE>
export EDAUTILS_LICENSE_FILE=$EDAUTILS_ROOT/edautils.lic
export PATH=$EDAUTILS_ROOT/bin:$PATH
export EDAUTILS_DISABLE_USAGE_TRACKING=1
```

### Launching

| Mode | Command |
|------|---------|
| Batch (SDC or Tcl script) | `sdc-shell -f constraints.sdc < /dev/null` (`-in constraints.sdc` and a bare `sdc-shell constraints.sdc` are the same) |
| Interactive | `sdc-shell` -- prompt `sdc-shell>`; `exit` or `quit` ends the session |
| Usage | `sdc-shell -help` (prints `Usage:  -in <Tcl command file>  [-verbose] [-help]`, exit 0) |

Options: `-verbose` logs every complete Tcl command before it runs (Note 1278
`Executing command: <text>`); `-suppress <id>:<id>...` silences those message ids; `-user <email>`.
`-in`, `-f`, `-help` and `-verbose` are matched case-insensitively. Any other argument is taken
as the script file name. (`-decrypt` also exists; it is used only by the release build to
generate the command reference and is not part of the supported interface.)

The banner is printed, then the licence is checked, then the shell sources `init.sdc.tcl` from
the protected files in `bin/tcl` and runs your file line by line from its path relative to the
current directory. Each SDC command executed is logged as
`<file>, Executing command : <command as evaluated>`.

#### Exit codes and how to judge a run

| Exit | Meaning |
|------|---------|
| 0 | The script reached its end (or `exit`), or `-help`. **Commands that failed do not change this** -- check the log. |
| 1 | The script file could not be opened (Error 700 `Failed to open file : '<file>' to read ...`), or `EDAUTILS_ROOT` unset (launcher). |
| 9 | Fatal start-up error in the licensing/init layer (`Fatal Error: Failed EDAUtils init() ...`). |
| 10 | No valid licence, or the licence does not enable `SDCBACKBONE` (Error 6404 `Failed to checkout LICENSE for the feature : SDCBACKBONE`). |
| 11 | Protected Tcl in `bin/tcl` failed its signature check (9410) or could not be decrypted (9422) -- wrong/old licence for this release, or a modified installation. |

The run ends with `Found N error(s) and M warning(s) ...`; a run is clean only when N is 0.

### Tcl command reference

- `doc/TclCommandReference.txt` -- generated at release time by running `<command> -help`
  for every command proc in the shipped `init.sdc.tcl`; each entry starts
  `[N] Command : <name>`. Here the SDC commands themselves are procs, so the reference covers
  the constraint commands (`create_clock`, `create_generated_clock`, `set_input_delay`,
  `set_false_path`, `set_multicycle_path`, ...), the object queries (`get_ports`, `get_pins`,
  `get_cells`, `get_nets`, `get_clocks`, `all_inputs`, ...) and `read_sdc` / `write_sdc` /
  `report_sdc`.
- At run time: `<command> -help` prints one command's usage; `info procs` lists the Tcl procs
  the command layer defines.
- `doc/html/` -- Java API (Javadoc) of the SDC data model and parser.

### Bundled point tools

Each has its own guide, copied from that tool's release. They run from `lib/sdc.jar` here (a
guide that names `lib/designplayer.jar` means the same jar under its standalone-bundle name).
Its examples ship under `tools/<tool>/examples/` (run them from there with `bin/` on `PATH`).

| Tool (guide) | Launcher in `bin/` |
|--------------|--------------------|
| [comparesdc](tools/comparesdc/AGENTS.md) | `comparesdc` (and `comparesdc.bat`) |
| [parsesdc](tools/parsesdc/AGENTS.md) | `parsesdc` (and `parsesdc.bat`) |
| [sdc2xls](tools/sdc2xls/AGENTS.md) | `sdc2xls` (and `sdc2xls.bat`) -- SDC to the constraint workbook (a sheet per category, mode / corner columns) |
| [sdclint](tools/sdclint/AGENTS.md) | `sdclint` (and `sdclint.bat`) |
| [xls2sdc](tools/xls2sdc/AGENTS.md) | `xls2sdc` (and `xls2sdc.bat`) -- the workbook back to SDC, one per mode; `-template` for an empty workbook |

### Examples

Run each from inside its directory with the environment above. The release self-test of this
bundle runs none of them.

| Directory | Command |
|-----------|---------|
| `examples/simple_constraint` | `sdc-shell -f simple_constraint.tcl` (no `runme.csh`; Tcl variables, `expr`, generated clocks and I/O delays on an Altera-style design) |
| `examples/comparesdc/trivial_constraints` | `comparesdc -revised simple_constraint.modified.tcl -golden simple_constraint.tcl -outfile Diff.rpt` (`runme.csh`) |

From the regression suite (reference: `tests.edautilscommandline/tests/constraints/test_1..4/runme.csh`
via `../runme_common.csh`; golden `sdc-shell.log.gld`, compared with the banner, memory lines
and message numbers filtered):

```
sdc-shell -f input.sdc
```

### Outputs and logs

- `sdc-shell.log` in the current directory: every message, and the closing
  `Found N error(s) and M warning(s)` line. Each run overwrites it (unless
  `EDAUTILS_APPEND_LOG_FILE` is used).
- Anything else is written only where your script's commands write it (e.g. `write_sdc`).
- Decrypted Tcl goes to a private temp folder under `java.io.tmpdir` and is deleted at exit.

### Common errors

| Symptom | Fix |
|---------|-----|
| `Environment variable EDAUTILS_ROOT is not set` | Export `EDAUTILS_ROOT` to the bundle root. |
| Exit 10, `Failed to checkout LICENSE for the feature : SDCBACKBONE` | Point `EDAUTILS_LICENSE_FILE` at a valid licence carrying `SDCBACKBONE` (the shipped `edautils.lic` expires; ask help@edautils.com for a new one). |
| Exit 11, message 9410 or 9422 | The licence is not one issued for this release, or `bin/tcl` was changed. Use the licence that came with this bundle, reinstall the bundle. |
| Exit 0 but the log says `Found N error(s)` with N > 0 | A command failed; the log names it and the line. Exit status alone is not a pass. |
| `Failed to open file : '<file>' to read` (exit 1) | Wrong file path; it is resolved from the current directory. |
| A multi-line command (lines ending `\`) is split or fails | Blanks after the trailing `\` end the continuation. Strip them (`sed 's/[[:blank:]]*$//'`) or set `EDAUTILS_TCL_ENABLE_SPACE_CHECK_IN_MULTILINE_CMD=1` (the shell then repairs a copy and says so in Warning 2200). |
| Run hangs at the `sdc-shell>` prompt | No script was given and stdin is a terminal; pass `-f <file>` and `</dev/null`. |
