# lib2verilog

> Generate empty Verilog modules (ports only) for every cell in a Liberty .lib library, for netlist compilation without vendor models.

- Catalog id: `Lib2verilog`; bundle: `lib2verilog`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: Liberty to Verilog, library stub generator, empty module, cell stubs, .lib to Verilog
- 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/lib2verilog.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Lib2verilog (latest file `lib2verilog-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/edautils-converters/files/lib2verilog/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/lib2verilog-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 a Liberty (`.lib`) library and writes an empty Verilog module (port list and directions
only, no body) for each selected cell into one file (default `output.v`) -- black-box stubs for
simulation, linting or netlist reading. Main class: `com.eu.miscedautils.lib2verilog.lib2verilog`
(jar `lib/lib2verilog.jar`).

### Where it ships

Its own bundle, `lib2verilog.tar.gz` (flow `lib2verilog`; release tree
`release_scripts/lib2verilog/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/lib2verilog` running the shell's jar; this guide as `tools/lib2verilog/AGENTS.md`, examples
under `tools/lib2verilog/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=$EDAUTILS_ROOT/lib/lib2verilog.jar`
  and prepends `bin/` to `PATH`.
- Licence feature `LIB2VERILOG`. 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 : LIB2VERILOG", exit status 10. (`README.txt` says
  `EDAUTILS_LICENSE_KEY`; that is stale -- the variable is `EDAUTILS_LICENSE_FILE`.)
- 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) for big libraries),
  `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.
- No external tools needed.

### Invocation

```
lib2verilog -in <file.lib> -cells <cell1:cell2> | -cells all | -all  [-out <file.v>]
```

| Option | Meaning |
|---|---|
| `-in <file>` | Liberty file (mandatory) |
| `-cells <c1:c2>` | Colon-separated cell names to convert; `all` (any case) converts every cell. One of `-cells`/`-all` is mandatory |
| `-all` | Convert every cell in the library (same as `-cells all`) |
| `-out <file>` | Output Verilog file (default `output.v`) |
| `-user <email>` | Usage-tracking user id |

There is **no `-help`**, `-nobanner`, `-quiet` or `-suppress`: any other word (including `-help`)
prints Error "Unrecognized option : <opt>" and the usage. With no arguments, or without `-in`, or
without a cell selection, only the usage is printed. An option given without its value throws an
index exception, reported as an internal error (exit 0).

### Inputs / Outputs

- Reads: the `-in` Liberty file (all `library` groups in it).
- Writes: `-out` (default `output.v` in the current directory), one `module <cell> ( ... );
  endmodule` per selected cell, in selection order. The file is created once parsing finishes,
  **even if no cell matched** (then it is empty).
- Port mapping: every `pin` and `pg_pin` becomes a scalar port; every `bus` becomes a vector port
  whose range comes from its `bus_type` (`bit_from`/`bit_to`, or `bit_width`). Directions map
  `input`/`output`/`inout`; any other or missing direction becomes `inout`. Names that are not
  plain identifiers are written as Verilog escaped identifiers (`\name `).
- Log: `lib2verilog.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (parse errors, cells not found,
  usage errors, internal exceptions). 1 = the `-out` file cannot be opened, out of memory, or
  `EDAUTILS_ROOT` missing/invalid (launcher). 10 = licence checkout failed.
- Message format: `lib2verilog: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit number. Usage lines have no severity or id.
- A requested cell that is absent logs Error "Cell '<c>' not found in the parsed library : <lib>"
  (once per `library` group searched); the other cells are still written.
- A successful run logs `Written outputs in file : <out>` and ends with
  `lib2verilog: Note: <id>: Found N error(s) and M warning(s) ...`.

### Examples

Shipped: `examples/i2c/` (`i2c.lib`, `runme.csh`):

```
cd $EDAUTILS_ROOT/examples/i2c
lib2verilog -in i2c.lib -cells i2c -out lib.v
```

From the regression suite (reference: `tests.edautilscommandline/tests/lib2verilog/`; cases use
`../runme_common.csh`, which runs `-cells <case>` unless the case sets `l2vargs`; goldens
`<case>.v.gld`, some with `lib2verilog.log.gld`):

```
lib2verilog -in i2c_rtl.lib -out i2c_rtl.v -cells i2c_rtl
lib2verilog -in attributes.lib -out attributes.v -cells all
lib2verilog -in gscl45nm.lib -out gscl45nm.v -all        # whole standard-cell library
```

### 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 `Written outputs in file` and
  `Found 0 error(s)` **and** the `-out` file is non-empty. An empty file with exit 0 means no
  requested cell was found.

### See also

verilog2lib (the reverse), parseliberty (Liberty round-trip and parser API).
