From 78aefb1b90ba0deb17bdab3042d9deff42d18d21 Mon Sep 17 00:00:00 2001 From: Gonzalo Larumbe Date: Thu, 14 Sep 2023 13:42:20 +0200 Subject: [PATCH] WIP: Updating README.md --- README.md | 91 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 55 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 9e381de..1eed770 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,10 @@ # verilog-ext.el - SystemVerilog Extensions for Emacs # -This package provides some extensions on top of the great Emacs [verilog-mode](https://github.com/veripool/verilog-mode): +This package provides useful extensions on top of [`verilog-mode`](https://github.com/veripool/verilog-mode) +and [`verilog-ts-mode`](https://github.com/gmlarumbe/verilog-ts-mode). -* [Tree-sitter powered `verilog-ts-mode`](#tree-sitter) +* [Tree-sitter `verilog-ts-mode` support](#tree-sitter) * [Improve syntax highlighting](#syntax-highlighting) * [Find definitions and references](#find-definitions-and-references) * [Auto-completion with dot and scope completion](#auto-completion) @@ -29,11 +30,15 @@ This package provides some extensions on top of the great Emacs [verilog-mode](h * [Auto-convert block end comments to names](#block-end-comments) * [Port connection utilities](#port-connections) +## Requirements ## + +- Emacs 29.1+ + ## Installation ## ### MELPA ### -`verilog-ext` and `verilog-ts-mode` are available on MELPA. `verilog-ext` includes `verilog-ts-mode` as a dependency. +`verilog-ext` is available on MELPA. ### straight.el ### @@ -76,21 +81,17 @@ By default all features are enabled: ports)) (verilog-ext-mode-setup) (add-hook 'verilog-mode-hook #'verilog-ext-mode) -;; To use `verilog-ts-mode' as the default major-mode also add the line below: -(add-to-list 'auto-mode-alist '("\\.s?vh?\\'" . verilog-ts-mode)) ``` If installed and loaded via `use-package`: ```elisp (use-package verilog-ext - :after verilog-mode - :demand :hook ((verilog-mode . verilog-ext-mode)) :init - ;; Can also be set through `M-x RET customize-group RET verilog-ext': - ;; - Verilog Ext Feature List (provides info of different features) - ;; Comment out/remove the ones you do not need + ;; Can also be set through `M-x RET customize-group RET verilog-ext': + ;; - Verilog Ext Feature List (provides info of different features) + ;; Comment out/remove the ones you do not need (setq verilog-ext-feature-list '(font-lock xref @@ -113,10 +114,6 @@ If installed and loaded via `use-package`: ports)) :config (verilog-ext-mode-setup)) - -;; To use `verilog-ts-mode' as the default major-mode also add the lines below: -(use-package verilog-ts-mode - :mode (("\\.s?vh?\\'" . verilog-ts-mode)) ``` ## Workspace ## @@ -192,15 +189,19 @@ Enabling of `verilog-ext-mode` minor-mode creates the following keybindings: # Features # -## Tree-sitter ## -The package `verilog-ts-mode` provides syntax highlighting, -indentation and a backend for hierarchy extraction, definitions and -references navigation, and some other features implemented in -`verilog-ext`. Using tree-sitter as a backend is recommended as it is -much faster and efficient than internal Emacs lisp parsing. +## Tree-sitter support ## + +Some of the features that `verilog-ext` provides are based either on +builtin `verilog-mode` Emacs lisp parsing or on tree-sitter `verilog-ts-mode`. + +It is possible to set up different backends for hierarchy extraction and +workspace tags collection for completion and navigation of definitions +and references. -`verilog-ts-mode` is derived from `verilog-mode` making AUTOs and other utilities still available. +Using tree-sitter as a backend is recommended as it is much faster and +efficient than internal Emacs lisp parsing. + For more information see the [wiki](https://github.com/gmlarumbe/verilog-ext/wiki/Tree-sitter). @@ -213,7 +214,7 @@ For configuration information, see the [wiki](https://github.com/gmlarumbe/veril ## Find definitions and references ## -`verilog-ext` provides a builtin `xref` backend to navigate definitions and references of the [workspace](#workspace). +`verilog-ext` provides an `xref` backend to navigate definitions and references of the [workspace](#workspace). @@ -425,29 +426,47 @@ For new functionality add new ERT tests if possible. Consider [sponsoring](https://github.com/sponsors/gmlarumbe) to help maintaining the project and for the development of new features. *Thank you!* -## ERT Tests setup ### +## ERT Tests ### + +### Setup ### + +To run the whole ERT test suite change directory to the `verilog-ext` +root and make sure `test-hdl` Git submodule has been loaded: + +```shell +git submodule update --init +``` + +### Targets ### -To run the whole ERT test suite change directory to the `verilog-ext` root and run the `test` target: +Then run the default target: ```shell -$ cd ~/.emacs.d/verilog-ext $ make ``` To run a subset of tests (e.g. navigation): ```shell -$ cd ~/.emacs.d/verilog-ext -$ make subset TESTS=navigation +$ make TESTS=navigation ``` -## Other packages +To regenerate all the expected outputs for the tests: + +```shell +$ make gen +``` -* [vhdl-ext](https://github.com/gmlarumbe/vhdl-ext): VHDL Extensions for Emacs - * Analog package to edit VHDL sources -* [fpga](https://github.com/gmlarumbe/fpga): FPGA & ASIC Utilities for Emacs - * Utilities for tools of major vendors of FPGA & ASIC -* [wavedrom-mode](https://github.com/gmlarumbe/wavedrom-mode): Wavedrom integration for Emacs - * Edit and render WaveJSON files to create timing diagrams -* [vunit-mode](https://github.com/embed-me/vunit-mode.git): VUnit Mode for Emacs - * Integration of [VUnit](https://github.com/VUnit/vunit) workflow. +To regenerate the expected outputs for a group of tests (e.g. navigation): + +```shell +$ make gen TESTS=navigation +``` + +## Other packages +* [verilog-ts-mode](https://github.com/gmlarumbe/verilog-ts-mode): SystemVerilog Tree-sitter mode +* [vhdl-ts-mode](https://github.com/gmlarumbe/vhdl-ts-mode): VHDL Tree-sitter mode +* [vhdl-ext](https://github.com/gmlarumbe/vhdl-ext): VHDL Extensions +* [fpga](https://github.com/gmlarumbe/fpga): FPGA & ASIC Utilities for tools of major vendors and open source +* [wavedrom-mode](https://github.com/gmlarumbe/wavedrom-mode): edit and render WaveJSON files to create timing diagrams +* [vunit-mode](https://github.com/embed-me/vunit-mode.git): Integration of [VUnit](https://github.com/VUnit/vunit) workflow