From 69b91bf89af9491e2ffb74ef2822c58a3f484b34 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 | 96 +++++++++++++++++++++++++++++++------------------- verilog-ext.el | 2 +- 2 files changed, 61 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 9e381de..cb30219 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,21 @@ 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+ +- Latest `verilog-mode` version +- Feature-specific binaries +- Optional: `tree-sitter` and `verilog-ts-mode` if using tree-sitter as a backend for some features + +For more info, see the [wiki](https://github.com/gmlarumbe/verilog-ext/wiki/Requirements). + + ## 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 +87,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 +120,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 ## @@ -193,15 +196,18 @@ 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. -`verilog-ts-mode` is derived from `verilog-mode` making AUTOs and other utilities still available. +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`. For example, hierarchy extraction and workspace +tags collection for completion and navigation of definitions and +references + +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). +For information about installation of `verilog-ts-mode` check its own +[repo](https://github.com/gmlarumbe/verilog-ts-mode). ## Syntax highlighting ## @@ -213,7 +219,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 +431,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 ### -To run the whole ERT test suite change directory to the `verilog-ext` root and run the `test` target: +### 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 ### + +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 diff --git a/verilog-ext.el b/verilog-ext.el index dd61cbb..452a9da 100644 --- a/verilog-ext.el +++ b/verilog-ext.el @@ -25,7 +25,7 @@ ;; Extensions for Verilog Mode: ;; -;; - Tree-sitter powered `verilog-ts-mode` support +;; - Tree-sitter `verilog-ts-mode` support ;; - Improved syntax highlighting ;; - Builtin xref backend ;; - Builtin capf function with dot and scope completion