Lint subcommand
The lint subcommand checks your Spice program for style and best-practice issues, like names that do not follow the naming
conventions or functions that grew too complex. It runs the compiler up to and including the type checker, so it also reports
all compile errors, but it does not generate any code.
Usage¶
The subcommand lints the main source file and all source files of your project, that it imports. The source files of the standard library and of external packages are left out.
Options¶
You can apply following options to the lint subcommand:
| Option | Short | Description |
|---|---|---|
--build-mode |
-m |
Controls the build mode. Valid values: debug (default), release and test. |
--build-var |
-b |
Add build variable to parametrize the compiled program (e.g. -b key=value). Can be passed multiple times |
--freestanding |
- | Lint for an environment without hosted libc, crt0 and OS, e.g. a kernel or firmware |
--debug-output |
-d |
Enable debug output |
--quiet |
-q |
Do not show the compile progress |
--dump-ast |
-ast |
Dump AST as serialized string and SVG image |
--dump-symtab |
- | Dump serialized symbol tables |
--dump-types |
- | Dump all used types |
--dump-cache-stats |
- | Dump stats for compiler-internal lookup caches |
--dump-dependency-graph |
- | Dump compile unit dependency graph |
--dump-stats |
- | Write compile statistics (stage times, peak memory usage, counters) as JSON to the given file |
The options, that only affect the code generation, like the optimization levels or --target, are not available,
because linting stops before the code generation.
Output¶
Every finding is printed on its own line with the location of the code, the id of the rule and a message:
| Text Only | |
|---|---|
The findings do not fail the subcommand: it exits with code 0, as long as the program compiles. Findings with the error
severity (see Configuration) are the exception: they are printed as [Lint error] and make the subcommand
exit with code 1. If there is a compile error, it reports the error and exits with code 1. The regular compiler warnings,
e.g. for unused variables, are not printed by the lint subcommand. You get them with the build subcommand.
Rules¶
The linter currently comes with the following rules:
| Rule id | Checks |
|---|---|
naming-convention |
Functions and procedures are named in camelCase, structs, interfaces and unions in PascalCase and global variables in SNAKE_CASE (uppercase letters, digits and underscores). Constructors and operator overloads are exempt |
too-many-parameters |
Functions and procedures have at most 6 parameters. Consider grouping related parameters into a struct |
cyclomatic-complexity |
Functions and procedures have a cyclomatic complexity of at most 10. It starts at 1 and every if, loop and case branch adds 1, including the ones in lambdas within the function. Consider splitting the function up |
The naming conventions follow the coding style guide.
Configuration¶
You can configure the rules in the [lint.rules] table of the manifest of your project, the spice.toml file, that also
describes your package for Spice Shaker. The lint subcommand uses the manifest
in the directory of the main source file or the nearest one in its parent directories. Without a manifest, all rules apply
with their default configuration. The format of the manifest is specified by the manifest package.
| TOML | |
|---|---|
Each rule accepts the following keys. Rules and keys, that you leave out, keep their default:
| Key | Default | Description |
|---|---|---|
enabled |
true |
Whether the rule runs at all |
severity |
"warning" |
Severity of the findings: "info", "warning" or "error". Findings with "error" fail the subcommand |
max |
see rules | Threshold of too-many-parameters (default: 6) and cyclomatic-complexity (default: 10). An integer of at least 1 |
The compiler rejects unknown rules and keys, so that a typo does not go unnoticed. It only reads the [lint] and [format]
tables of the manifest and leaves the other ones to Spice Shaker.
Suppressing findings¶
To suppress all findings for a source file, add the core.compiler.warnings.ignore attribute to it. It also suppresses the
compiler warnings for the file:
| Spice | |
|---|---|
Examples¶
| Bash | |
|---|---|