| commit | f303140370c136722050cb56df8bf14e9db8d2e2 | [log] [tgz] |
|---|---|---|
| author | hzeller <h.zeller@acm.org> | Wed Apr 16 16:41:13 2025 +0000 |
| committer | hzeller <h.zeller@acm.org> | Wed Apr 16 16:41:13 2025 +0000 |
| tree | 0bdd500f394d1a1564fecaa505dfb247550c6f5d | |
| parent | 26d8a2fa4edbb3f71b7e4ee44a6d5aa17103fe92 [diff] |
Deploying to gh-pages from @ chipsalliance/verible@d0f83bfdc3963a40a43a3fa639a0ee28f2e2067d 🚀
Verible
The Verible project's main mission is to parse SystemVerilog (IEEE 1800-2017) (as standardized in the SV-LRM) for a wide variety of applications, including developer tools.
It was born out of a need to parse un-preprocessed source files, which is suitable for single-file applications like style-linting and formatting. In doing so, it can be adapted to parse preprocessed source files, which is what real compilers and toolchains require.
The spirit of the project is that no-one should ever have to develop a SystemVerilog parser for their own application, because developing a standard-compliant parser is an enormous task due to the syntactic complexity of the language. Verible's parser is also regularly tested against an ever-growing suite of (tool-independent) language compliance tests at https://symbiflow.github.io/sv-tests/.
A lesser (but notable) objective is that the language-agnostic components of Verible be usable for rapidly developing language support tools for other languages.
For simple installation, we provide regular binary releases for Linux and Windows, including statically linked binaries for x86 and Arm to run on almost any Linux distribution.
There are also some distributions that include Verible
If you prefer to build and install the binaries locally yourself, see details below in the Developers section.
Learn more about the parser implementation here.
We provide a standalone verible-verilog-syntax tool to help with visualizing the syntax structure as understood by the lexer and parser. This is very useful for troubleshooting and understand the internal representations 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 a Python wrapper module and a few example scripts.
verible-verilog-lint identifies constructs or patterns in code that are deemed undesirable according to a style guide. The main goal is to relieve humans the burden of reviewing code for style compliance. Many lint rules use syntax tree pattern matching to find style violations.
Features:
Documentation:
The verible-verilog-format formatter manages whitespace in accordance with a particular style. The main goal is to relieve humans of having to manually manage whitespace, wrapping, and indentation, and to provide a tool that can be integrated into any editor to enable editor-independent consistency.
Features (various degress of work-in-progress):
The verible-verilog-ls is a language server that provides the functionalities that come with the Verible command line tools also directly in your editor.
It implements the standardized language server protocol that is supported by a myriad of editors and IDEs.
The language server provides formatting and linting. If possible, it also provides quick-fixes
verible-verilog-diff compares two input files for equivalence.
verible-verilog-project is a multi-tool that operates on whole Verilog projects, consisting of a file list and related configurations. This serves as a diagnostic tool for analyzing (and potentially transforming) project-level sources.
verible-verilog-obfuscate transforms Verilog code by replacing identifiers with obfuscated names of equal length, and preserving all other text, including spaces. Output is written to stdout. The resulting file size is the same as the original. This is useful for preparing potentially sensitive test cases with tool vendors.
verible-verilog-preprocessor is a collection of preprocessor-like tools, (but does not include a fully-featured Verilog preprocessor yet.)
verible-verilog-kythe-extractor extracts indexing facts from SV source code using the Kythe schema, which can then enhance IDEs with linked cross-references for ease of source code navigation.
For source code browsing, we recommend using the fully-indexed and searchable mirror at https://cs.opensource.google/verible/verible.
If you'd like to contribute, check out the contributing guide and the development resources.
Verible's code base is written in C++.
To build, you need the bazel build system and a C++17 compatible 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 with the nix package manager simply run nix-shell to get a build environment.
# Build all tools and libraries bazel build -c opt //...
You can access the generated artifacts under bazel-bin/. For instance the syntax checker will be at bazel-bin/verible/verilog/tools/syntax/verible-verilog-syntax (corresponding to the target name //verible/verilog/tools/syntax:verible-verilog-syntax).
Moreover, if you need statically linked executables that don't depend on your shared libraries, you can use custom config create_static_linked_executables (with this setting bfd linker will be used, instead of default gold 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 part of 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 bazel command line:
# Also append the option '--//bazel:use_local_flex_bison' to test/install commands bazel build -c opt --//bazel:use_local_flex_bison //...
Building on Windows requires LLVM, WinFlexBison 3 and Git-bash to be installed. Using package manager chocolatey, 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 regular binary 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 compliant install utility, otherwise simply copy the binaries from bazel-bin/ to your desired location)
We strongly encourage running the test suite using bazel:
# Run all tests bazel test -c opt //...
Whenever adding new features in file, say, foo.cc always make sure to also update (or add) the corresponding foo_test.cc. Once you've written the test, you can use .github/bin/generate-coverage-html.sh to double-check that you have covered all code-paths in your test; narrow the coverage run to your test to make sure coverage is not accidentally coming from unrelated 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!
The Verible team is interested in exploring how it can help other tool developers in providing a SystemVerilog front end, for example, emitting an abstract syntax tree (AST) or possibly even provide more higher-level UHDM format. If you are interested in collaborating, contact us.