Command Line Reference

Reference information about all command line options.

General

-h,--help

Display help text about command line options and exit.

--version

Display slang version information and exit.

-q,--quiet

Don't print non-essential output status.

--std (1800-2017 | 1800-2023 | latest)

Sets the version of the SystemVerilog language to use. This changes how the code is parsed and elaborated and which language features are available to use. The current default is 1800-2017, though this may change in the future. Using "latest" will use the latest available version, currently 1800-2023.

positional arguments

Paths to files (using file patterns) that should be included in the compilation.

--single-unit

Causes the tool to treat all input files as being part of a single compilation unit. By default all files are considered to be separate compilation units and ordering between them does not matter. When this option is provided, all files are concatenated together, in order, to produce a single compilation unit. See Compilation Units for more discussion.

-v,--libfile <file-pattern>[,...]

Adds files to the compilation, like a positional argument, except that the files are considered to be Verilog source libraries. Libraries are always their own compilation unit even when compiling with --single-unit, and modules within them are never automatically instantiated.

-f <file-pattern>[,...]

Opens the given "command files" containing lists of arguments to process in addition to the ones provided on the command line itself. Any file paths in the files are relative to the current working directory.

See Command Files for more information about command files.

-F <file-pattern>[,...]

See Command Files for more information about command files.

-C <file-pattern>[,...]

Opens the given "compilation unit listing files" containing lists of files and arguments used to create separate compilation units. Any file paths in the files are relative to the unit listing file itself.

See Compilation Unit Listing for more information about compilation unit listings.

--exclude-ext <ext>

Any provided positional arguments that have extensions matching <ext> will be ignored. This option is typically used when projects have existing command files listing sources that are not SystemVerilog code.

-j,--threads <count>

Controls the number of threads used for parallel compilation. slang will by default use the number of threads supported by the system – this can be set to some other value to more specifically control the concurrency. Setting it to 1 will disable the use of threading.

Note that multithreading only currently applies to the parsing stage of compilation, and that it is not supported when running with --single-unit

Actions

These options control what action the tool will perform when run. They are mutually exclusive. If none of these are provided, the default action is to elaborate the design, print any diagnostics, and exit.

-E,--preprocess

Treat all files as a single input file (as if --single-unit had been passed), run the preprocessor on them, and then print the preprocessed text to stdout. If errors occur during preprocessing, they will be printed instead of the preprocessed text.

--macros-only

Run the preprocessor on all input files, print out any macros that are discovered, and exit. No diagnostics will be printed.

--parse-only

Perform parsing of all input files but don't perform type checking and elaboration. All diagnostics encountered will be printed.

--lint-only

Only perform linting of code, don't try to elaborate a full hierarchy.

Include paths and macros

-I,--include-directory <dir-pattern>[,...]
+incdir+<dir>[+<dir>...]

Add the given directory paths to the list of directories searched by `include directives that use quotes to specify the path.

--isystem <dir-pattern>[,...]

Add the given directory paths to the list of directories searched by `include directives that use angle brackets to specify the path.

-D,--define-macro <macro>=<value>
+define+<macro>=<value>[+<macro>=<value>...]

Define <macro> to <value> (or 1 if <value> is ommitted) at the start of all source files. Example:

slang -DFOO=2 -DBAR=asdf -D BAZ=3

-U,--undefine-macro <macro>

Undefine the given macro at the start of all source files.

Preprocessor

--comments

When running in preprocessor-only mode (using -E) include comments in the preprocessed output text.

--directives

When running in preprocessor-only mode (using -E) include directives in the preprocessed output text.

--max-include-depth <depth>

Set the maximum depth of nested include files. Exceeding this limit will cause an error. The default is 1024.

--libraries-inherit-macros

If true, library files will inherit macro definitions from the primary source files. By default library files are independent and will not inherit macros from the main project. --single-unit must also be passed when this option is used.

--enable-legacy-protect

Enables use of legacy source protection directives for compatibility with older tools.

--obfuscate-ids

Causes all identifiers in the preprocessed output to be replaced with obfuscated alphanumeric strings.

Parsing

--max-parse-depth <depth>

Set the maximum depth of nested language elements. This is a measure of the depth of the parsing stack, which is checked against this limit to avoid stack overflows. The default is 1024.

--max-lexer-errors <depth>

Set the maximum number of errors that can occur during lexing before the rest of the file is skipped. The default is 64.

-y,--libdir <dir-pattern>[,...]

Add the given directory paths to the list of directories searched when an unknown module instantiation or package import is encountered. Combined with --libext, files are automatically included based on the name that is unknown. This list is empty by default.

The search works as follows: all known modules, interfaces, programs, packages, and classes add their names to a list of known definitions. Any instantiations, package import directives, or double colon-scoped names that reference a name not in the list of known definitions will trigger a search in all library directories, trying all specified library extensions. If a matching file is found it will be loaded and parsed in its entirety, and the algorithm will be triggered again on any new names found.

See Searching for Library Files for more details.

-Y,--libext <ext>

Add the given extension to the list of extensions tried when searching for files to satisfy unknown module instantiations and package imports. This list automatically includes '.v' and '.sv' by default.

JSON Output

--ast-json <file>

Dump the compiled AST in JSON format to the specified file, or '-' for stdout.

--ast-json-scope <path>

When dumping AST to JSON, include only the scope (or symbol) specified by the given hierarchical path. This option can be specified more than once to include more than one scope. If not provided, all symbols are dumped.

--ast-json-source-info

When dumping AST to JSON, include source line and file information.

Compilation

--top <name>

Specifies the name of a module or program that should be instantiated at the root of the design. Can be specified more than once to instantiate multiple top-level modules. The module (or program) specified must not have any non-defaulted parameters or interface ports.

Additionally, you can specify the name of one or more SystemVerilog configurations. The cells specified in the design statement of those configurations will become the top levels of the design. If the name of a configuration overlaps with that of a module/interface/program definition, the latter will be taken by default. You can use a :config suffix on the name to explicitly select the configuration.

If no top modules are specified manually, they will be automatically inferred by finding all modules that are not instantiated elsewhere in the design.

-L <library>[,...]

A list of library names in the order in which they should be used to resolve module names. Libraries that are earlier in the list will be searched before ones later in the list.

If no explicit ordering is given the default order is the order in which the libraries are specified to the tool.

--defaultLibName <name>

Sets the name of the default library. If not set, defaults to "work".

--max-hierarchy-depth <depth>

Set the maximum depth of the design hierarchy. Used to detect infinite module instantiation recursion. The default is 128.

--max-generate-steps <steps>

Set the maximum number of steps that can occur during generate block evaluation before giving up. Used to detect infinite generate loops. The default is 131072.

--max-constexpr-depth <depth>

Set the maximum depth of the constant evaluation call stack. Used to detect infinite recursion during constant evaluation. The default is 128.

--max-constexpr-steps <steps>

Set the maximum number of steps that can occur during constant evaluation before giving up. Used to detect infinite constant evaluation loops. The default is 100000.

--constexpr-backtrace-limit <limit>

Set the maximum number of frames to show when printing a constant evaluation backtrace in diagnostics; the rest will be abbreviated to avoid spamming output. The default is 10.

--max-instance-array <limit>

Set the maximum number of instances allowed in a single instance array. The limit exists to prevent runaway compilation times on invalid input. The default is 65535.

--max-udp-coverage-notes <limit>

When reporting a warning for a UDP that doesn't cover all possible input edge transitions, limit the number of notes printed to this value to avoid excessively large diagnostic output. The default is 8.

--compat vcs

Attempt to increase compatibility with the specified tool. Various options will be set and some warnings will be silenced to mimic the given tool as closely as possible. Currently only 'vcs' is supported as a value.

-T,--timing min|typ|max

Select which expressions in min:typ:max triplets should be processed as part of the compilation. By default this will be the "typical", or middle expression.

--timescale <base>/<precision>

Specifies a default time scale to use for design elements that don't explicitly provide one. If this option is not set, there is no default and an error will be issued if not all elements have a time scale specified. Example: --timescale=1ns/1ns

-G <name>=<value>

Override all parameters with the given name in top-level modules to the provided value. This option can be specified more than once to override multiple parameters.

--allow-use-before-declare

Don't issue an error if an identifier is used before its declaration. This is not allowed in SystemVerilog – this option is provided for compatibility with tools that have weaker enforcement of this rule.

--allow-hierarchical-const

Allow hierarchical references in constant expressions. SystemVerilog doesn't permit this, but many popular tools allow it anyway so this flag can be used for compatibility purposes.

--relax-enum-conversions

Allow all integral types to convert implicitly to enum types in assignments. SystemVerilog doesn't permit this, but some tools allow it anyway so this flag can be used for compatibility purposes.

--relax-string-conversions

Allow string types to convert implicitly to integral types in assignments. SystemVerilog doesn't permit this, but some tools allow it anyway so this flag can be used for compatibility purposes.

--allow-dup-initial-drivers

Allow signals driven by always_comb or always_ff procedures to also be driven by initial blocks. SystemVerilog doesn't permit this, but some tools allow it anyway so this flag can be used for compatibility purposes.

--allow-toplevel-iface-ports

Allow top-level modules to have interface ports. SystemVerilog doesn't permit this, but some tools allow it anyway so this flag can be used for compatibility purposes.

--allow-recursive-implicit-call

Allow implicit call expressions (ones that lack parentheses) to be recursive function calls. The LRM states that directly recursive function calls require parentheses but many other tools allow this anyway so this flag can be used for compatibility purposes.

--allow-bare-value-param-assigment

Allow module instantiations to provide a single parameter value assignment without enclosing it in parentheses. SystemVerilog doesn't permit this, but some tools allow it anyway so this flag can be used for compatibility purposes.

--allow-self-determined-stream-concat

Allow self-determined streaming concatenation expressions. SystemVerilog only permits these expressions in assignment-like contexts but some tools allow it anyway so this flag can be used for compatibility purposes.

--allow-multi-driven-locals

Allow subroutine local variables to be driven from multiple always_comb/always_ff blocks. The LRM does not make an exception for local variables in assignment rules but most tools allow it anyway so this flag exists for compatibility with those tools.

--allow-merging-ansi-ports

Allow ANSI port declarations to merge with a net or variable declaration internal to the instance, instead of creating a new internal symbol to connect to. This is not allowed in SystemVerilog but some tools support it anyway so this flag can be used for compatibility purposes.

For example:

module m(input a, output b);
    wire [31:0] a;
    logic [31:0] b;
    assign b = a;
endmodule

--strict-driver-checking

Perform strict driver checking, which currently means disabling procedural 'for' Driver loop unrolling

Diagnostic Control

--color-diagnostics

Always print diagnostics in color. If this option is unset, colors will be enabled if a color-capable terminal is detected.

--diag-column

Show or hide column numbers in diagnostic output. The default is to show.

--diag-location

Show or hide location information (file name, line and column numbers) in diagnostic output. The default is to show.

--diag-source

Show or hide source code and caret location in diagnostic output. The default is to show.

--diag-option

Show or hide warning option names in diagnostic output. The default is to show.

--diag-include-stack

Show or hide file include stacks in diagnostic output. The default is to show.

--diag-macro-expansion

Show or hide macro expansion backtraces in diagnostic output. The default is to show.

--diag-hierarchy always|never|auto

Show or hide hierarchy locations in diagnostic output. The default is 'auto', which decides whether to show the hierarchical path based on heuristics. 'always' will show the paths on every diagnostic, and 'never' will suppress them.

--suppress-warnings <file-pattern>[,...]

One or more paths in which to suppress warnings. Use this if you want to generally turn on warnings for your project and have it build cleanly but have some files which you can't modify for some reason.

--suppress-macro-warnings <file-pattern>[,...]

One or more paths in which to suppress warnings that originate from macro expansions. This means that warnings inside of macros that are defined within these paths will be suppressed, even if the macros are expanded into files that are not within these paths.

--error-limit

Set a limit on the number of errors that will be printed. Setting this to zero will disable the limit. The default is 64.

--ignore-unknown-modules

Don't issue an error for instantiations of unknown modules, interface, and programs.

-Wfoo

Enable warning "foo". See Warning Reference for a complete list of warnings that can be enabled this way.

-Wno-foo

Disable warning "foo".

-Wnone

Disable all warnings.

-Weverything

Enable all warnings.

-Werror

Treat all warnings as errors.

-Werror=foo

Treat warning "foo" as an error.

-Wno-error=foo

Turn warning "foo" into a warning even if -Werror is specified.

Legacy Vendor Command Support

--cmd-ignore <vendor_cmd>,<N>

Define rule to ignore vendor command <vendor_cmd> with its following <N> parameters. A command of the form +xyz will also match any vendor command of the form +xyz+abc, as +abc is the command's argument, and doesn't need to be matched. This option is typically used to ignore commands listed in command files that are meant for some other tool.

--cmd-rename <vendor_cmd>,<slang_cmd>

Define rule to rename vendor command <vendor_cmd> into existing <slang_cmd>. Similarly to --cmd-ignore, this exists to support existing command files that specify options with different names.

--ignore-directive <vendor_directive>

Some tool vendors declare custom preprocessor directives, and slang fails when encountering those. By using this command line option with the vendor's directive, it will be ignored (the vendor directive should be specified without the leading ` symbol). It is possible to use this command line option multiple times, to ignore multiple vendor directives. Please note that any vendor directive ignored also ignores all optional parameters until the end of the line.

Profiling

--time-trace <path>

Run slang with time tracing enabled, which collects information about how long various parts of the compilation take. When the program exits it will write the trace results to the given file, which is JSON text containing events in the Chrome Trace Event format.