# preprocessverilog

> IEEE 1800 SystemVerilog preprocessor: expand `define macros, `include files and `ifdef conditionals and write the preprocessed source.

- Catalog id: `Preprocessverilog`; bundle: `preprocessverilog`; latest version 20261018
- Documentation page: https://edautils.com/DownloadLinks.html
- Keywords: Verilog preprocessor, SystemVerilog preprocessor, macro expansion, ifdef, include
- 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/preprocessverilog.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Preprocessverilog (latest file `preprocessverilog-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/system-verilog-parser/files/preprocessverilog/
- SourceForge: https://sourceforge.net/projects/edautils-free-utilities/files/preprocessverilog/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/preprocessverilog-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.

Runs the Verilog/SystemVerilog preprocessor on one or more source files: resolves
`` `define``/`` `ifdef``/`` `include`` and the other compiler directives and writes the
preprocessed text of each input file. It can also handle `` `pragma protect`` blocks using
the key options, and generate an RSA key pair. It does not build a design model and has no
`-top`. Main class: `com.eu.miscedautils.verilogparser.PreProcessVerilog`
(jar `lib/verilogparser.jar`).

### Where it ships

Its own bundle, `preprocessverilog.tar.gz` (flow `preprocessverilog`; release tree
`release_scripts/preprocessverilog/1.0`), and as a point tool in the **designplayer-shell** bundle
(`bin/preprocessverilog` running the shell's jar; this guide as
`tools/preprocessverilog/AGENTS.md`, examples under `tools/preprocessverilog/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` and prepends `bin/` to `PATH`.
- Licence: a valid licence file only; no feature is checked. The licence file is searched in
  this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run directory),
  `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`. No valid licence: exit status 10,
  no message.
- 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 external tools needed.

### Invocation

```
preprocessverilog -in <file.v> | -f <filelist>  [-out <file>]  [+incdir+<p1>+<p2>]
                  [+define+A+B=1]  [options]
preprocessverilog -generate_keys
```

This tool parses its own command line (it does **not** use the shared `FVPProcessCmdLineArgs`
reader), so only these options exist:

| Option | Meaning |
|---|---|
| `-in <file>` | Input file (wildcards expanded unless `-nowildcard`) |
| `-f <filelist>` | One file per line; `+define+` and `+incdir+` lines allowed; wildcards expanded |
| `-out <file>` | Output file. Without it each input goes to `VlogPP/<file name>` in the current directory |
| `+incdir+<p1>+<p2>` | Include search paths |
| `+define+A+B=1` | Macros (`=value`: digits become an integer value, anything else a string) |
| `-ignore_metacomment <vendor\|*> <directive\|*>` | Repeatable. The text between matching fences (`// synopsys translate_off` ... `translate_on`, `/* */` too; vendors and directives as in the `parseverilog` guide) is dropped from the output exactly as an inactive `` `ifdef`` branch is: nothing is written, and `` `define``, `` `undef``, `` `include``, `` `ifdef``/`` `endif`` inside it are not acted on. Newlines are kept so line numbers hold; the fence comments themselves stay in the output. Fences no rule matches pass through unchanged, comments included. Warnings 20010-20013 for nested/unbalanced/unterminated fences. Also works with the key options (token-based path), where dropped text also loses its newlines |
| `-mark_metacomment <vendor\|*> <directive\|*>` | Recognise a user vendor's fences; the text is kept (`-ignore_metacomment` wins) |
| `-flatten` | One flattened output text: `` `include`` is inlined, `` `line <n> "<file>" <1\|2>`` markers keep source locations, and all inputs (`-in`, `-f`, wildcards) are written to the one `-out` file in order, sharing macros |
| `-nowildcard` | Do not expand wildcards in file names |
| `-encryption_key <16 chars>` | AES key (128 bit) for protected blocks |
| `-encryption_algorithm <alg>` | Algorithm (usage: default AES) |
| `-private_key_file <f>` / `-public_key_file <f>` | RSA key files |
| `-keyowner <name>` / `-keyname <name>` | Key owner / key name |
| `-generate_keys` | Generate an RSA key pair (`key.pvt.dat`, `key.pub.dat` in the current directory) and stop; options after it are ignored |
| `-toolprefix <name>` | Listed in the usage, but has **no effect** (the prefix is set before parsing) |
| `-user <email>` | Usage-tracking user |
| `-nobanner` | No banner and no completion summary |
| `-dbg` | Debug mode |
| `-help` | Print usage and return (`-h` is not recognised: error 7041 and usage) |

A value option given as the last argument raises an internal exception (reported in the log,
exit 0). The shipped `README.txt` shows `-key` and `-algorithm`; the code only accepts
`-encryption_key` and `-encryption_algorithm`.

### Inputs / Outputs

- Reads: the files from `-in` / `-f` and their `` `include`` files. A missing input file is
  Fatal Error 9412 and that file is skipped.
- Writes: with `-out`, every input file is written to that one path in turn, so with several
  inputs only the **last** one survives; use `-f` without `-out` for several files, which
  writes `VlogPP/<basename>` per file (same basename twice overwrites). If the output cannot
  be created a temporary `edautils_temp_file*.v` is used (warning 6249).
- Log: **`PreProcessVerilog.log`** (mixed case) in the current directory; override with
  `EDAUTILS_LOG_FILE` (there is no `-l` option). Messages are prefixed `PreProcessVerilog:`.

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (missing files, unrecognised
  option). 10 = no valid licence file. 1 = `EDAUTILS_ROOT` missing/invalid, or out of memory
  (Fatal Error 3092, JVM halted).
- Message format: `PreProcessVerilog: <Severity>: <id>: <text>`, severity one of `Error`,
  `Fatal Error`, `Warning`, `Note`; usage lines have no severity or id.
- The run ends with `PreProcessVerilog: Note: <id>: Found N error(s) and M warning(s) ...`.
  This summary is **not printed with `-nobanner`**. Each written file is reported by
  Note 2354 "Writtten the preprocessed RTL in the file : <path>".

### Examples

Shipped: `examples/example_1/` (`runme.csh`, `runme.bat`, `example_1.v`):

```
cd $EDAUTILS_ROOT/examples/example_1
preprocessverilog -in example_1.v -out modified_example.v
```

From the regression suite (reference:
`tests.edautilscommandline/tests/preprocessverilog/define_ifdefs/runme.csh`, compared by
`../runme_common.csh`):

```
preprocessverilog -nowildcard -in define_ifdefs.v -out decompiled.v
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes `PreProcessVerilog.log` and `VlogPP/` 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** `PreProcessVerilog.log` contains `Found 0 error(s)`
  (do not use `-nobanner`) **and** the expected output file(s) exist.

### See also

parseverilog (full parse; its bundle also carries a `preprocessverilog` launcher), uniquifyverilog.
