# verilog2lib

> Generate a Liberty .lib library shell from Verilog modules: one cell per module with its pins and directions.

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

## Downloads

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

Parses Verilog/SystemVerilog and writes a Liberty (`.lib`) library with one `cell` per selected
module, holding its pins and buses with directions (no timing or power data -- a pin-interface
view). Library, cell and pin attributes can be injected from a config file. Output is one file
(default `output.lib`). Main class: `com.eu.miscedautils.verilog2lib.verilog2lib`
(jar `lib/verilog2lib.jar`).

### Where it ships

Its own bundle, `verilog2lib.tar.gz` (flow `verilog2lib`; release tree
`release_scripts/verilog2lib/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/verilog2lib` running the shell's jar; this guide as `tools/verilog2lib/AGENTS.md`, examples
under `tools/verilog2lib/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/verilog2lib.jar`
  and prepends `bin/` to `PATH`.
- Licence feature `VERILOG2LIB`. 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 : VERILOG2LIB", 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) for big designs),
  `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_LIBRARY_MAP_FILE` (map file for `-dump`/`-restore`, default `libmap.ini`).
- No external tools needed.

### Invocation

```
verilog2lib -in <file.v> | -f <files.list>  -top <module> | -modules <m1:m2>
            [-out <file.lib>] [-libname <name>] [-cfg <config.cfg>]
            [-bitblast [-prefixslash]] [-notypeincell]
            [-v95] [-nowildcard] [+incdir+<d1>+<d2>] [+define+<M1>+<M2>=<val>]
            [-nobanner] [-quiet] [-suppress <id1:id2>]
```

Tool options:

| Option | Meaning |
|---|---|
| `-top <module>` | Module to convert |
| `-modules <m1:m2>` | Colon-separated modules to convert (added after `-top` if both are given). One of `-top`/`-modules`/`-all` is needed |
| `-all` | Convert every module, only when neither `-top` nor `-modules` is given. **Needs `-libname`** (see below) |
| `-out <file>` | Output Liberty file (default `output.lib`) |
| `-libname <name>` | Library name (default: the first module converted) |
| `-cfg <file>` | Config file of attributes copied into the library/cell/pin groups (format below) |
| `-bitblast` | Write each bit of a vector port as its own pin `name[i]` instead of a bus |
| `-prefixslash` | With `-bitblast`, prefix those pin names with `\` |
| `-notypeincell` | Put the `type (bus_<l>_<r>)` declarations at library scope instead of in each cell |
| `-help`, `-h` | Print the usage and return |

Verilog front-end options (shared with the other Verilog tools):

| Option | Meaning |
|---|---|
| `-in <file>` | One Verilog file; wildcard-expanded unless `-nowildcard` |
| `-f <file>` | File list (one file per line; `+incdir+`/`+define+` lines allowed); repeatable. `-in` wins if both are given |
| `-excludefilelist <file>` | Files to drop from the input list |
| `-v95` | Parse as Verilog-95/2001 (SystemVerilog keywords off); default is SystemVerilog |
| `-nowildcard` | No wildcard expansion of `-in` |
| `+incdir+<d1>+<d2>` | Include search paths (environment variables expanded) |
| `+define+<M>[=<v>]+...` | Predefine macros |
| `-nokeywords <k1:k2>` | Words not to treat as keywords (the suite uses `-nokeywords do`) |
| `-blackbox` | Create black boxes for undefined modules |
| `-declare_wires_for_undefined_obects` | Declare wires for undeclared objects (spelling as in the code) |
| `-l <file>` / `-la <file>` | Log file name / append to it |
| `-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 |
| `-dump`, `-restore <units>`, `-work <lib>`, `-mapfile <file>` | Save/load precompiled design units |
| `-encryption_key`, `-encryption_algorithm`, `-private_key_file`, `-public_key_file` | Encrypted-source options |
| `-dbg` | Parser debug tracing |
| `-user <email>` | Usage-tracking user id |

The usage line also shows `-sort` and `-noparameval`; **neither is accepted** here. Any
unrecognised word prints Error "Unrecognized option : <opt>" and the usage. `-libname`,
`-modules`, `-cfg` and `-user` given as the last word, with no value, are also reported as
unrecognised. Without `-in` and `-f` only the usage is printed.

#### `-all` writes nothing without `-libname`

With `-all` and no `-top`/`-modules`, the library name is never defaulted, so the run finishes
(exit 0, no error) **without writing the output file**. Always pair `-all` with `-libname <name>`.

#### Config file (`-cfg`)

Sections `$library`, `$cell`, `$pin`, each closed by `$end`. Every line inside a section is copied
verbatim into the library group, into **every** cell group, or into **every** pin group
respectively:

```
$library
    time_unit : "1ns";
    technology ( cmos );
$end
$cell
    dont_touch : true;
$end
$pin
    max_capacitance : 0.137429;
$end
```

Only those three sections are recognised. Any other section (e.g. `$bus`) and lines outside a
section are **silently ignored** -- the shipped `examples/config/config.cfg` has a `$bus` section
that has no effect. Lines are not checked for Liberty syntax. An unreadable config file logs
Error "Failed to read configuration file file : <f>" and the run stops without writing output.

### Inputs / Outputs

- Reads: the Verilog sources, include files and the `-cfg` file.
- Writes: `-out` (default `output.lib` in the current directory), only if at least one cell was
  built. Scalar ports become `pin`s; vector ports become `bus`es typed `bus_<left>_<right>`
  (or bit-blasted pins with `-bitblast`). Directions map `input`/`output`/`inout`.
- Also creates the directory `myEdaUtilsWork/` in the current directory (Verilog work library),
  even when nothing is dumped.
- Log: `verilog2lib.log` in the current directory (override with `-l`/`-la` or `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (parse errors, modules 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: `verilog2lib: <Severity>: <id>: <text>`, severity one of `Error`,
  `Programming Error`, `Fatal Error`, `Warning`, `Note`; `<id>` is a 5-digit number.
- Key messages: Error "The top module named <m> not found ..." (that module is skipped, others are
  still converted), Error "You must specify module(s) to be converted with the -top or the
  -modules switch ...", Note `Written Library in file : <out>`. The run ends with
  `Found N error(s) and M warning(s) ...` (not with `-nobanner`).
- Verilog elaboration messages count as errors even when the library is correct: the
  `bustype` regression golden records 5 `Programming Error` lines ("More than one net/object while
  processing expression ...") with a correct `.lib`.

### Examples

Shipped: `examples/i2c/` (the i2c RTL, `files.list`, `runme.csh`) and `examples/config/`
(`i2c.v`, `inc/i2c_defs.v`, `config.cfg`, `runme.csh`):

```
cd $EDAUTILS_ROOT/examples/i2c
verilog2lib -nowildcard -f files.list -out i2c.lib -top i2c -notypeincell -bitblast -prefixslash -v95
cd $EDAUTILS_ROOT/examples/config
verilog2lib -in i2c.v -out i2c.lib -top i2c -cfg config.cfg +incdir+inc -v95
```

From the regression suite (reference: `tests.edautilscommandline/tests/verilog2lib/`; goldens
`<case>.lib.gld` and `verilog2lib.log.gld`):

```
verilog2lib -nowildcard -f files.txt -out bustype.lib -top i2c -notypeincell -v95
verilog2lib -nokeywords do -in i2c.v -out i2c.lib -top i2c -cfg config.cfg     # case config
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log, `myEdaUtilsWork/` and the default output 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 `Written Library in file` **and** the `-out`
  file exists. Check the `Error:` lines too, but see the note above: a non-zero error count from
  the Verilog front end does not by itself mean the `.lib` is wrong. Delete a stale `-out` first.

### See also

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