/** @page command-line-ref Command Line Reference
@brief Reference information about all command line options

@tableofcontents

@section general 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.

`positional arguments`

Paths to files 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.

`-v <filename>`

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

`-f <filename>`

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

See @ref command-files for more information about command files.

`-F <filename>`

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

See @ref command-files for more information about command files.

@section 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.

@section include-paths Include paths and macros

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

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

`--isystem <dir>`

Add the given directory path 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:

@code{.ansi}
slang -DFOO=2 -DBAR=asdf -D BAZ=3
@endcode

`-U,--undefine-macro <macro>`

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

@section clr-preprocessor 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.

@section clr-parsing 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>`

Add the given directory path 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.

`-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.

@section json-output 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.

@section compilation-limits Compilation

`--top <name>`

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

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

`--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.

`--compat vcs`

Attempt to increase compatibility with the specified tool. Various options will
be set and 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.

`-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.

`--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.

`--strict-driver-checking`

Perform strict driver checking, which currently means disabling procedural 'for' @ref loop-unroll

@section diag-control 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`

Show or hide hierarchy locations in diagnostic output. The default is to show.

`--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 @ref warning-ref 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.

*/
