Skip to content
SystemVerilog Studio

Emacs verilog-auto

Many teams write port lists and instance connections with the /*AUTO*/ comments of Emacs verilog-mode: /*AUTOINST*/ in an instance stands for its connections, and verilog-mode writes them out. SystemVerilog Studio expands AUTOs itself (see verilog-mode AUTOs) and writes the same code as Emacs in most cases; that page notes the deliberate differences in each AUTO’s section. Use an Emacs verilog-auto run configuration when you want Emacs’s own result, for example because your team’s checks compare files with it, or to run a particular version of verilog-mode. A run configuration is a named set of settings you start with the Run button (see Run configurations). This one runs Emacs on a file, and the editor shows the expanded file when Emacs is done.

Try it

Section titled “Try it”

You need Emacs on your PATH (check with emacs --version in a terminal; to install it, use brew install emacs on macOS or your Linux package manager); verilog-mode comes with it. Open the sample project with File | Open… and wait until the progress bar at the bottom right of the IDE (indexing) has finished. Step 2 changes rtl/edge_pair.v, and Emacs writes it back in step 3. On a laptop, function keys such as Shift+F10 may need Fn. To start over, unzip the sample project again.

  1. Create a configuration. Open rtl/edge_pair.v. Choose Run | Edit Configurations…, click +, choose SystemVerilog Studio | Emacs verilog-auto, type verilog-auto in Name, leave File empty (the file in the editor) and click OK.
  2. Remove the connections. In the instance u_a (the line edge_det u_a (/*AUTOINST*/), select from just after /*AUTOINST*/ up to, but not including, the ); that ends the instance, after (a) on its .d line, and press Delete. The line now reads edge_det u_a (/*AUTOINST*/); followed by the leftover comment // Templated (leave it: Emacs rewrites the line). Leave u_b as it is. Save the file (⌘S / Ctrl+S).
  3. Run it. Click in the edge_pair.v editor, select verilog-auto in the run-configuration drop-down in the top toolbar and click the green Run triangle (⌃R on macOS, Shift+F10 on Windows/Linux). The Run tool window shows the command line, …/emacs --batch --no-site-file …/rtl/edge_pair.v -f verilog-batch-auto (… stands for the full paths on your machine) and the exit code 0, and the editor shows u_a with its connections written back: // Outputs, .hist connected to hist_a[1:0], .rise to rise_a, // Inputs, .clk to clk and .d to a, the templated ones ending in // Templated, just like u_b, which you did not touch. The AUTO_TEMPLATE comment above the instances tells verilog-mode to connect d to a for u_a (see AUTO_TEMPLATE).

The file is now exactly as it was before step 2: Emacs wrote back what you deleted. If it is not, copy rtl/edge_pair.v from a fresh unzip of the sample project. To remove the configuration, select it in Run | Edit Configurations… and click the minus button.

How it works

Section titled “How it works”

The configuration runs emacs --batch --no-site-file [-l verilog-mode.el] file -f verilog-batch-auto (-l only when verilog-mode.el is set): Emacs expands the AUTOs of the file and saves it, and the editor reloads it.

If the file has unsaved changes, the configuration does not run (Emacs would overwrite them): save first.

Emacs finds the modules a file instantiates by its own rules, not from the IDE project or your compile file: in the same file, in the file’s folder, and in the folders the file’s Local Variables name (verilog-library-directories; see Local variables). The sample keeps edge_det in the same file. On your own code, a module in another folder needs a block like this at the end of the file:

// Local Variables:
// verilog-library-directories:("." "../blocks")
// End:

Settings

Section titled “Settings”

Open the configuration with Run | Edit Configurations… and select it in the list on the left.

Setting Meaning
Emacs executable Empty: emacs on the PATH.
File Empty: the SystemVerilog file selected in the editor. A path; a relative one starts at the project directory.
verilog-mode.el Empty: the verilog-mode that comes with Emacs; a path loads another version with -l.
Emacs options Extra options, inserted right after --batch. Default: --no-site-file, which skips the machine-wide Emacs start-up file, so the result does not depend on how Emacs is set up on this computer.

If it doesn’t work

Section titled “If it doesn’t work”
You see Likely cause What to do
Save edge_pair.v first: Emacs rewrites the file The file has unsaved changes Save the file first (⌘S / Ctrl+S)
Open a SystemVerilog file in the editor, or choose the file here File is empty and no SystemVerilog file is selected in the editor Click in the edge_pair.v editor tab, or set File
%Error: …: Can’t locate ‘sub’ module definition (the quotes may be straight) and an exit code other than 0; the file is unchanged The instantiated module is in a folder Emacs does not search Name its folder in the file’s Local Variables (see How it works) and run again
Another exit code other than 0, with an Emacs error in the Run tool window Emacs could not load verilog-mode or expand the file Look for the line starting with %Error: (above the Lisp backtrace); check that verilog-mode.el is empty or names an existing file; run the command line from the Run tool window in a terminal
emacs was not found on the PATH: set the path of the executable, although it works in a terminal The IDE does not have your shell’s PATH Enter the full path in Emacs executable (which emacs in a terminal gives it, for example /opt/homebrew/bin/emacs), or start the IDE from a terminal

See also Troubleshooting.

Limitations

Section titled “Limitations”
  • Run only: the configurations cannot be debugged.
  • Tested on macOS and Linux; Windows is untested.

More in Known limitations: Run configurations.

Section titled “Related”