Repository files navigation

The Verible project's main mission is to parse SystemVerilog (IEEE 1800-2017)(as standardized in theSV-LRM) for a wide variety of applications, includingdeveloper tools.

It was born out of a need to parseun-preprocessed source files, which issuitable for single-file applications like style-linting and formatting. Indoing so, it can be adapted to parsepreprocessed source files, which is whatreal compilers and toolchains require.

The spirit of the project is that no-one should ever have to develop aSystemVerilog parser for their own application, because developing astandard-compliant parser is an enormous task due to the syntactic complexity ofthe language. Verible's parser is also regularly tested against an ever-growingsuite of (tool-independent) language compliance tests athttps://symbiflow.github.io/sv-tests/.

A lesser (but notable) objective is that the language-agnostic components ofVerible be usable for rapidly developing language support tools for otherlanguages.

For simple installation, we provide regularbinary releases for Linux andWindows, including statically linked binaries for x86 and Arm to run on almostany Linux distribution.

There are also some distributions that include Verible

• Nix has binaries for Linux x86 and Arm.
• There is ahomebrew package for MacOS.

If you prefer to build and install the binaries locally yourself, seedetails below in theDevelopers section.

Learn more about the parser implementation here.

We provide a standaloneverible-verilog-syntax toolto help with visualizing the syntax structure as understood by the lexer andparser. This is very useful for troubleshooting and understand the internalrepresentations seen by the other tools.

The tool has an ability of exporting a concrete syntax tree in JSON format,making use of it in external tools easy. There is also aPython wrapper module and a few example scripts.

verible-verilog-lint identifies constructs or patternsin code that are deemed undesirable according to a style guide. The main goal isto relieve humans the burden of reviewing code for style compliance. Manylint rules use syntax tree pattern matching to find styleviolations.

Features:

• Style guide citations in diagnostics
• Rule deck configurability
• Waiver mechanisms: in-file, external waiver file
• Github SystemVerilog linter action available.

Documentation:

• Style linter user documentation
• Generated lint rule documentation

Theverible-verilog-format formatter manageswhitespace in accordance with a particular style. The main goal is to relievehumans of having to manually manage whitespace, wrapping, and indentation, andto provide a tool that can be integrated into any editor to enableeditor-independent consistency.

Features (various degress of work-in-progress):

• Corrects indentation
• Corrects inter-token spacing, with syntax context awareness
• Line-wrapping to a column limit
• Support for incremental formatting, only touched changed lines.
• Interactive formatting: accept or decline formatting changes
• Tabular alignment
• Github SystemVerilog formatter action available.

Theverible-verilog-ls is a language server thatprovides the functionalities that come with the Verible command line toolsalso directly in your editor.

It implements the standardizedlanguage server protocol that is supportedby a myriad of editors and IDEs.

The language server provides formatting and linting. If possible, it alsoprovides quick-fixes

verible-verilog-diff compares two input files forequivalence.

verible-verilog-project is a multi-tool thatoperates on whole Verilog projects, consisting of a file list and relatedconfigurations. This serves as a diagnostic tool for analyzing (and potentiallytransforming) project-level sources.

verible-verilog-obfuscate transforms Verilogcode by replacing identifiers with obfuscated names of equal length, andpreserving all other text, including spaces. Output is written to stdout. Theresulting file size is the same as the original. This is useful for preparingpotentially sensitive test cases with tool vendors.

verible-verilog-preprocessor is a collectionof preprocessor-like tools, (but does not include a fully-featured Verilogpreprocessor yet.)

verible-verilog-kythe-extractor extracts indexingfacts from SV source code using theKythe schema, which canthen enhance IDEs with linked cross-references for ease of source codenavigation.

For source code browsing, we recommend using the fully-indexed and searchablemirror athttps://cs.opensource.google/verible/verible.

If you'd like to contribute, check out thecontributingguide and thedevelopment resources.

Verible's code base is written in C++.

To build, you need thebazel build system and a C++17compatible compiler (e.g. >= g++-10), as well as python3.A lot of users of Verible have to work on pretty old installations,so we try to keep the requirements as minimal as possible.

Use your package manager to install the dependencies; on a system withthe nix package manager simply runnix-shell to get a build environment.

# Build all tools and librariesbazel build -c opt //...

You can access the generated artifacts underbazel-bin/. For instance thesyntax checker will be atbazel-bin/verible/verilog/tools/syntax/verible-verilog-syntax (corresponding to thetarget name//verible/verilog/tools/syntax:verible-verilog-syntax).

Moreover, if you need statically linked executables that don't depend on yourshared libraries, you can use custom configcreate_static_linked_executables (with this settingbfd linker will be used,instead of defaultgold linker).

# Generate statically linked executables.# Uses bfd linker and needs static system libs available.bazel build -c opt --config=create_static_linked_executables //...

Flex and Bison, that are needed for the parser generation, are compiled as partof the build process. But if for any reason you want or need local tools (e.g.if you encounter a compile problem with them - please file a bug then)can choose so by adding--//bazel:use_local_flex_bison to your bazelcommand line:

# Also append the option '--//bazel:use_local_flex_bison' to test/install commandsbazel build -c opt  --//bazel:use_local_flex_bison //...

Building on Windows requires LLVM, WinFlexBison 3 and Git-bash to be installed. Using package managerchocolatey, this can be done with

choco install git llvm winflexbison3

Bazel may also require environment variable to use git-bash and LLVM, on powershell

$env:BAZEL_SH="C:\Program Files\Git\git-bash.exe"$env:BAZEL_LLVM="C:\Program Files\LLVM"

For simple installation, we provide regularbinary releases.

If you prefer to build and install the binaries locally yourself:

bazel build -c opt :install-binaries# Install in your home directory.github/bin/simple-install.sh~/bin# For a system directory that requires root-access, call scfript with sudo.sudo .github/bin/simple-install.sh /usr/local/bin

(this requies a compliantinstall utility, otherwise simply copythe binaries frombazel-bin/ to your desired location)

We strongly encourage running the test suite usingbazel:

# Run all testsbazeltest -c opt //...

Whenever adding new features in file, say,foo.cc always make sure to alsoupdate (or add) the correspondingfoo_test.cc. Once you've written thetest, you can use.github/bin/generate-coverage-html.sh to double-checkthat you have covered all code-paths in your test; narrow the coveragerun to your test to make sure coverage is not accidentally coming fromunrelated tests that happen to use the library:

MODE=coverage .github/bin/build-and-test.sh //foo/bar:foo_test.github/bin/generate-coverage-html.sh

Join the Verible community!

• Developers:verible-dev@googlegroups.com(join)
• Users:verible-users@googlegroups.com(join)

The Verible team is interested in exploring how it can help other tooldevelopers in providing a SystemVerilog front end, for example, emitting anabstract syntax tree (AST) or possibly even provide more higher-levelUHDM format. If you are interested in collaborating, contact us.