CLI Reference

Every option of ryusim and its subcommands, as of RyuSim 2.1.16.

The command line has one shape:

The subcommands are compile, coverage merge, coverage html and profile. Global options go before the subcommand. After it they are rejected: ryusim compile -q design.sv fails with The following argument was not expected: -q. Run ryusim --help or ryusim <subcommand> --help for the built-in summary.

Each table gives the option, its default, and what it does. A default in brackets in --help is copied as is; "off" means a flag that is not set, and "none" means an option with no value until you give one. Options marked No effect in 2.1.16 are accepted and then ignored: the value is parsed and never used.

Global options

Option	Default	Description
-V, --version	off	Prints RyuSim 2.1.16 and exits 0.
-v, --verbose	off	Prints extra detail: each source file added, each define, include path and parameter override, the auto-detected top module, and the PCH cache key. For coverage merge it has the same effect as that subcommand's --verbose.
-q, --quiet, --silent	off	Suppresses the progress lines ([1/4] Parsing SystemVerilog... and so on). Errors and warnings are still printed on stderr.
-O, --opt-level N	2	Clang optimization level, 0 to 3, for the generated code that runs every time step (the "hot" pool). One-time setup code is built at -O0 regardless. The level used is recorded as hot_opt in <Mdir>/ryusim-route.json. Out-of-range values exit 105. Like every global option it goes before compile: ryusim compile -O 3 design.sv fails with sources: File does not exist: 3.
--stats	off	After a successful build, prints a === Compilation Statistics === block: source file count, module count, top module, optimization level and output directory. Prints nothing with --lint-only or --codegen-only.
-g, --debug-info	off	No effect in 2.1.16. The generated build is not compiled with -g.
--warn-all	off	No effect in 2.1.16.
--warn-error	off	No effect in 2.1.16. Warnings do not change the exit status.
--Wlint, --warn-lint	off	No effect in 2.1.16.
--Wunused, --warn-unused	off	No effect in 2.1.16.
--inline-mult N	16	No effect in 2.1.16. The value must be a positive integer.
--unroll-count N	8	No effect in 2.1.16. The value must be a positive integer.

--gpu is listed under diagnostic and developer options.

compile

ryusim compile parses and elaborates the sources, generates C++, and builds it with Clang into a simulation executable. With the default output directory and top module tb, the files it leaves are:

• obj_dir/build/tb_sim: the executable. Run it directly. Its own options are listed under The simulation executable.
• obj_dir/libtb.so: the same model as a shared library, which cocotb loads.
• obj_dir/ryusim-route.json: which code path built each module, the init policy, and the optimization levels.

Sources and top level

Option	Default	Description
sources ...	none	Files to compile. .sv and .v files go to the SystemVerilog frontend. .c, .cc, .cpp and .cxx files are compiled as DPI-C code and linked into the simulation (see DPI-C). Each file must exist. At least one source or one -f list is required. When the design imports a DPI-C function, every .c file in the directories of the SystemVerilog sources is also compiled in; this scan is deprecated, so pass DPI sources on the command line.
-f, --filelist file	none	Reads source paths from file, one per line. Blank lines and lines starting with # or // are skipped, and leading and trailing blanks are trimmed. Every other line is taken as a file path, relative to the current directory; option lines such as +incdir+ or a nested -f are not recognized. Repeatable.
--top module	none	Names the primary top module: the executable is called <module>_sim. Every other module that nothing instantiates is still elaborated and simulated alongside it (IEEE 1800-2023 23.3.1); use --top-only to stop that. Without --top, RyuSim picks the last uninstantiated module in source order, preferring one that prints output. With --top, elaboration errors outside that module's hierarchy are reported and the compile continues; errors inside it exit 1. A name that matches no module exits 1 with Error: Top module 'module' not found in design.
--top-only	off	Makes the --top module the only elaboration root, whether or not another module instantiates it; modules not reachable from it are not elaborated. This matches iverilog -s and verilator --top-module. Requires --top (exit 107 without it). cocotbext-ryusim passes --top but not --top-only; add it through COMPILE_ARGS (see cocotb).
-I, --include dir	none	Adds a directory to the `include search path. The directory must exist. Repeatable.
-D, --define NAME[=VALUE]	none	Defines a preprocessor macro for the SystemVerilog sources. -DNAME alone defines it as 1. A bare value that looks like a file (ends in .sv, .v, .vh or .h, or contains /) is rejected, so -D design.sv is an error rather than a define. Repeatable.
-G, --parameter NAME=VALUE	none	Overrides a parameter of the top-level module. Both -GWIDTH=16 and -G WIDTH=16 work. A string value needs its quotes: -G 'NAME="abc"'. Repeatable.
--dpi-define NAME[=VALUE]	none	Defines a preprocessor macro for the C and C++ DPI sources only. The SystemVerilog preprocessor never sees it. Repeatable.

Output

Option	Default	Description
-o, --Mdir dir	obj_dir	Directory for the generated C++, the build files and the executable. Created if it does not exist.
--lint-only	off	Parses, elaborates and runs the unsupported-construct check, then stops. Nothing is written and no output directory is created. Prints Lint passed - no errors found and exits 0, or exits 1 on errors. The --top name is not checked in this mode.
--codegen-only	off	Writes the generated C++, CMakeLists.txt, build.ninja and ryusim-route.json, then stops before building and prints the command to build by hand (ninja -C obj_dir).
-j, --jobs N	0	Parallel jobs for the Clang build. 0 uses the number of logical CPUs, capped at 8.

Waveforms

The options below apply when the executable runs. File names are relative to the directory the executable runs in. See Waveforms for viewing them and for $dumpfile/$dumpvars in the design.

Option	Default	Description
--trace-vcd	off	Writes a VCD of the whole design from time 0. If the design also calls $dumpfile/$dumpvars, the flag wins, the dump tasks do nothing, and the compile prints a warning saying so.
--trace-vcd-file file	trace.vcd	Name of the VCD file. --help says the default is <top_module>.vcd; the file actually written is trace.vcd. Takes effect only with --trace-vcd.
--trace-fst	off	Writes an FST (the compressed GTKWave format) of the whole design. Can be combined with --trace-vcd to get both files from one run.
--trace-fst-file file	trace.fst	Name of the FST file. As with the VCD file, --help says <top_module>.fst but the default written is trace.fst. Takes effect only with --trace-fst.
--trace-depth N	0	Number of hierarchy levels to trace. 1 is the top module's own signals only; 0 is unlimited. When the design's own $dumpvars drives the dump, this replaces its levels argument and the compile prints a warning.
--trace-max-width N	0	Leaves out signals wider than N bits. 0 is unlimited.

Coverage

Any of the --coverage* enable flags below turns coverage on. The executable writes an LCOV file when it exits. The Coverage page walks through a full run.

Option	Default	Description
--coverage	off	Enables line coverage. Branch, toggle, FSM, functional and assertion coverage each need their own flag.
--coverage-file file	coverage.info	LCOV output file, relative to the directory the executable runs in.
--coverage-line	off	Enables line coverage. The output is the same as with --coverage; the flag does not remove anything the other flags add.
--coverage-branch	off	Adds branch coverage for if/else and case (LCOV BRDA records).
--coverage-toggle	off	Adds toggle coverage: a count of 0-to-1 and 1-to-0 transitions per signal bit.
--coverage-fsm	off	Adds FSM coverage: the states and transitions of detected state machines. Partial in 2.1.16: the FSM records are written with zero hits. See Coverage.
--coverage-functional	off	Adds functional coverage from covergroups and coverpoints.
--coverage-assert	off	Adds assertion coverage. For each assert property the file counts four outcomes: PASS, FAIL, VACUOUS and DISABLED.
--coverage-exclude-pragmas, --coverage-no-exclude	on	No effect in 2.1.16. Neither spelling changes how coverage exclusion pragmas are handled.
--coverage-warn-nested, --no-coverage-warn-nested	on	No effect in 2.1.16.
--coverage-warn-unclosed, --no-coverage-warn-unclosed	on	No effect in 2.1.16.

Initialization and 2-state

What these change, and a design that shows it, is on Initialization and 2-state.

Option	Default	Description
--init-reg policy	x	Start value of 4-state variables that have no initializer: x (the IEEE 1800-2023 default), zero, one or random. Memories (unpacked arrays) follow --init-mem instead. Any other value exits 105. See start-value options.
--init-mem policy	x	The same choice for unpacked arrays and memories. See start-value options.
--no-x-init	off	Shorthand for --init-reg zero --init-mem zero. An explicit --init-reg or --init-mem wins over it for that kind of storage. Combined with an explicit x it exits 105: --no-x-init conflicts with an explicit --init-reg=x / --init-mem=x; drop one of the flags. See start-value options.
--2state, --two-state	off	Simulates signals with two states, 0 and 1, instead of four. Partial in 2.1.16: some out-of-range reads still return X, and a design with any module on the older code generator is refused (see the 2-state limits). Implies --init-reg zero --init-mem zero unless one or random is given. Conflicts with --all-four-state and with an explicit x policy (exit 105). The semantics are under two-state mode.
--all-four-state	off	Keeps every value in its 4-state representation by turning off RyuSim's two-state lowering (the two-state pass of --opt). Useful as a reference build when comparing results. Recorded as "all_four_state": true in ryusim-route.json.

Assertions and randomization

Option	Default	Description
--assertions on|off	on	off disables concurrent assertion evaluation from time 0, as if the design called $assertoff at the start. $asserton in the design turns it back on. Immediate assertions are not affected.
--assume-check	off	Checks immediate assume statements as if they were immediate assert statements, so a false one runs its else branch. Concurrent assume property is always checked.
--sva-recursion-limit N	0	Maximum number of live recursive-property attempts per instance. 0 means the built-in limit of 100000. Reaching the limit is a runtime error.
--verbose-randomize-failure	off	Whenever randomize() returns 0, prints the constraint blocks involved with their file and line. The plusarg +ryusim_verbose_randomize_failure turns the same report on for one run without recompiling.

Timing and limits

Option	Default	Description
--timescale unit/precision	none	Time unit and precision for design elements that have no `timescale directive, for example 1ns/1ps. Source directives always win. The magnitude must be 1, 10 or 100, and the precision cannot be coarser than the unit; anything else exits 105. Without it, directive-less elements use 1ps/1ps.
--max-time time	none	No effect in 2.1.16. The simulation is not stopped at the given time. End it from the design with $finish, or from the testbench.
--max-settle-iters N	0	Maximum settle iterations within one time slot before the simulation stops with an error, which catches combinational loops that never settle. 0 means the built-in limit of 10000.

Performance

What these options do to run time is on Performance. -O is a global option.

Option	Default	Description
--threads N	1	Number of threads the generated model may use. 0 and 1 both mean one thread. RyuSim estimates the gain from splitting the design; when it predicts less than 1.2 times the single-thread speed, it prints Note: partition: refused ... and builds a single-thread model. Any value above 1 also selects the older fixpoint scheduler, even when the split is refused, and says so on stderr (Note: trigger schedule unavailable). The environment variable RYUSIM_THREADS lowers the count at run time. Performance says when threads help.
--opt spec	all on	Turns typed-IR optimization passes on or off. spec is a comma list of pass names; a leading - turns that pass off, as in --opt=-cse,-fusion. The passes are coverage, flat-eval, dce, two-state, cse, const-fold, fusion, handle-elide, process-class, trigger-schedule, nba-elision, partition (on only with --threads above 1), and preeval, which folds calls to pure functions with constant arguments during elaboration. All others are on by default. Repeatable; a later setting for the same pass wins. A name that matches no pass is ignored without a message.
--pch-cache dir	$XDG_CACHE_HOME/ryusim/pch, else $HOME/.cache/ryusim/pch	Directory for the precompiled header of the RyuSim runtime, shared by every compile from the same RyuSim binary. The cache key covers the RyuSim version, its headers, the compiler and the flags. off builds the header inside each output directory instead. If the directory cannot be created, the compile warns and builds it per output directory.

Warnings and diagnostics

In 2.1.16 ryusim compile does not print the SystemVerilog frontend's warnings, such as width mismatches or oversized literals. It does print its own warnings, for example for a combinational loop, for --trace-vcd overriding $dumpvars, and for constructs let through by --unsupported=warn. The warning options below are accepted for compatibility with other tools' command lines, and none of them has an effect.

Option	Default	Description
--unsupported error|warn	error	What to do with a construct RyuSim can parse but cannot simulate yet. error reports unsupported construct: name and exits 1. warn reports the same message as a warning and continues, for triage only: the construct does not simulate correctly. The check also runs with --lint-only. See the Compliance Matrix for what is supported.
--Werror, --warnings-as-errors	off	No effect in 2.1.16.
--Wall	off	No effect in 2.1.16.
--Wextra	off	No effect in 2.1.16.
--Wno-unused	off	No effect in 2.1.16.
--Wno-width	off	No effect in 2.1.16.
--Wno-implicit	off	No effect in 2.1.16.
--error-limit N	100	No effect in 2.1.16. Every error is printed.
--diagnostics-sarif[=file]	off	No effect in 2.1.16. No SARIF file is written, with or without a file name.
--color, --no-color	on	No effect in 2.1.16. Diagnostics are printed without ANSI color codes either way.

IEEE 1735

Option	Default	Description
--broker-url URL	https://broker.ryusim.com/api/v1	Key broker that RyuSim asks for keys when a source file contains IEEE 1735 protected envelopes. If RYUSIM_API_KEY is set, it is sent as a bearer token. See IEEE 1735 IP Protection.

Configuration and plugins

Option	Default	Description
--config file	none	No effect in 2.1.16. The file must exist and is read as JSON, but its settings (top module, defines, include paths) are not applied. Pass them as options.
--plugin file	none	No effect in 2.1.16. Nothing is loaded, and a path that does not exist is not reported.
--vpi-depth N	-1	How many hierarchy levels of signals are registered for VPI access, which is what cocotb uses. -1 is unlimited, 0 is the top module only; the maximum is 100.

coverage merge

ryusim coverage merge -o out in... combines LCOV files from several runs into one. Each input must exist and parse as LCOV; otherwise it exits 1 (or 105 for a missing file).

Option	Default	Description
-o, --output file	none (required)	File to write the merged data to.
--verbose	off	Prints each input with its source file count, then totals: input files, source files, lines hit/found and branches hit/found.
--quiet	off	Prints nothing except errors.
--strict	off	No effect in 2.1.16.

coverage html

ryusim coverage html -o dir file turns one LCOV file into an HTML report by running genhtml from the lcov package. Without genhtml on the PATH it exits 1 with Error: genhtml command not found.

Option	Default	Description
-o, --output dir	none (required)	Directory for the report. Open dir/index.html.
--title text	RyuSim Coverage Report	Title shown on the report pages.
--branch-coverage	off	Shows branch data in the report (passes --branch-coverage to genhtml).
--highlight	off	Passes --highlight to genhtml.

profile

Not implemented in 2.1.16. ryusim profile neither compiles nor runs the design. It checks that the source files exist and prints a fixed report with every time at 0 ms and the --cycles value echoed back. Do not use it to measure a design; Performance covers what to use instead.

Option	Default	Description
--top module	none	Echoed in the header; otherwise unused.
-o, --output file	none	Writes the report to file instead of stdout.
--format text|json	text	Report format.
--cycles N	0	Echoed in the report; nothing is simulated.
-v, --verbose	off	Adds Verbose mode: enabled to the header.

The simulation executable

The executable that ryusim compile builds takes a few options of its own, printed by obj_dir/build/<top>_sim --help:

Option	Description
--seed N	Root seed for randomization. The seed comes from, in order: --seed, the plusarg +ryusim_seed=N, the environment variable RANDOM_SEED, then a random value. The run prints the seed and where it came from, as in RyuSim: effective root seed = 9 (source: --seed).
+plusarg	Passed to $test$plusargs and $value$plusargs.
--vpi-load lib	Loads a VPI library and calls its vlog_startup_routines. Repeatable. cocotb uses this.
--vpi	Runs in VPI mode without loading a library.
-h, --help	Prints the usage and exits 0.

Any other argument exits 1 with ERROR: unrecognized argument. The exceptions are -D, -G, -I, --timescale= and --coverage arguments, which older Makefiles passed to the executable too: they print WARNING: ignoring compile-time argument and are ignored.

Environment variables

Variable	Read by	Description
RYUSIM_API_KEY	ryusim compile	Sent to the IEEE 1735 key broker as Authorization: Bearer key. Optional: without it, requests go out unauthenticated.
XDG_CACHE_HOME, HOME	ryusim compile	Locate the default --pch-cache directory.
RYUSIM_MARCH	ryusim compile	The -march level the generated code is built for. By default RyuSim uses the highest x86-64 level (x86-64, -v2, -v3 or -v4) the compiling machine supports, so an executable built on a newer CPU may not run on an older one. Set x86-64 for an executable that runs on any x86-64 machine, native for -march=native, or off for no -march flag. Other values print a warning and fall back to the default. Non-x86 hosts get no flag.
RYUSIM_BUILD_DRIVER	ryusim compile	ninja (the default) or cmake, the tool that runs the Clang build. Any other value prints a warning and uses CMake. The driver used is recorded as build_driver in ryusim-route.json.
RANDOM_SEED	the simulation	Root seed, used when neither --seed nor +ryusim_seed= is given.
RYUSIM_THREADS	the simulation	Lowers the thread count of a model built with --threads N. It cannot raise it above N; values below 1 are ignored.

Build-tuning variables are listed under diagnostic and developer options.

Exit status

Code	Meaning
0	Success. Also returned for --help, --version, and ryusim with no subcommand, which prints the help.
1	The design did not compile: a SystemVerilog error, an unsupported construct under --unsupported=error, an unknown --top, or a failed Clang build. Also a failed coverage merge or coverage html.
105	An option value failed its check: a missing input file, an out-of-range number, an invalid policy, or two options that conflict.
106	A required argument is missing, such as compile with no sources.
107	An option needs another option: --top-only without --top.
109	An unknown option or subcommand, or a global option placed after the subcommand.
114	An option is missing its value, such as a trailing --top.

Codes 100 to 127 all come from the command-line parser; the ones above are those you are likely to hit. The simulation executable exits 0 when the run ends normally. It exits 1 if the design called $fatal or $error, including a failed immediate assert and a concurrent assertion whose else branch calls $error. A concurrent assertion with no action block prints ERROR: Assertion 'name' FAILED but does not change the exit status: the run still exits 0. Under VPI (cocotb) it exits 0, and cocotb reports the result in results.xml.

Examples

Each example runs as shown in an empty directory.

Pick the elaboration root

This file has two modules that nothing instantiates:

With --top top_a alone, both modules are roots and both run:

Add --top-only and only top_a is elaborated:

Override a parameter, define a macro, read a file list

Trace only the top level

A module with one child:

Write a VCD named top_only.vcd that stops at the top level, then list its scopes and signals:

Without --trace-depth 1 the file also has a u_leaf scope with d and q.

Check the exit status of a bad command line

Diagnostic and developer options (unstable)

These exist to debug RyuSim itself. Their names, output and behavior can change in any release.

Option	Default	Description
--gpu (global)	off	Deprecated. Does nothing except print warning: --gpu is deprecated and has no effect in v2 (GPU offload is parked; see release notes).
--dump-typed-ir	off	Prints RyuSim's typed intermediate representation to stdout after conversion, then continues the compile.
--dump-ir-after pass	none	Prints the typed intermediate representation to stderr after the named pass runs. Pass names are listed under --opt.
--threads-force	off	For testing only. Makes --threads split the design even when the predicted gain is below the threshold.
--hot-opt level	the -O level	Clang level (O0, O1, O2, O3 or Os) for the per-time-step code. Overrides -O for that code. Without the flag, RYUSIM_HOT_OPT is read.
--cold-opt level	O0	Clang level for the cold file of each module (<module>__slow.cpp): constructors, initialization, initial blocks, fork branch bodies and concurrent assertion evaluation. User functions and tasks are in the hot file. Without the flag, RYUSIM_COLD_OPT is read.

Developer environment variables, read by ryusim compile:

• RYUSIM_HOT_OPT, RYUSIM_COLD_OPT: the --hot-opt and --cold-opt values when the flags are absent.
• RYUSIM_ASAN=1, RYUSIM_TSAN=1: build the executable with AddressSanitizer or ThreadSanitizer. Setting both is an error.
• RYUSIM_O1_TU_BYTES, RYUSIM_O0_TU_BYTES, RYUSIM_O1_FN_BYTES, RYUSIM_O0_FN_BYTES, RYUSIM_TU_BATCH_BYTES, RYUSIM_EVAL_CHUNK_BYTES, RYUSIM_EVAL_CHUNK_MIN_BYTES: size thresholds, in bytes, at which very large generated files are built at a lower optimization level, batched, or split. 0 turns a threshold off.