Rename conflicts

A rename is safe when every usage still refers to the same declaration afterwards, and nothing else starts referring to it. Before changing any file, the plugin simulates the new name using the same lookup rules as name resolution. If the new name would silently break or re-bind code, you see a warning and can cancel, instead of finding the damage later. For example, renaming state to count in the sample project would make state <= IDLE assign to the output port count instead.

Try it

The steps use the sample project; open it and wait for indexing first. Cancelling leaves every file unchanged.

1. Open rtl/counter.sv and put the caret (the text cursor) on the second word, the variable name state (not the type state_t), in state_t state;.

2. Press ⇧F6 (macOS) / Shift+F6 (Windows/Linux), or right-click and choose Refactor | Rename…. Type count and click Refactor (if the name is edited in place instead, type count and press Enter). count is already the name of an output port of the module.

3. The Conflicts Detected dialog lists two problems: 'count' is already declared in this scope, and what would break as a result, Usage of 'state' in 'state <= IDLE' would refer to another declaration of 'count'.

   

4. Click Cancel. Nothing is changed: state is still state. (Refactor Anyway would rename it regardless, leaving the code the dialog described.)

If no dialog appears, see If it doesn’t work.

What the dialog does

If the plugin finds problems, the IDE shows the Conflicts Detected dialog listing them. Usually only the first problem of each kind is listed; fixing it may reveal another. Choose Cancel, or Refactor Anyway if you are sure (for example when you are about to fix the other declaration too). The check follows SystemVerilog’s name spaces: a module and a signal, or a package and a variable, may share a name, so renaming a signal to the name of a module is not a conflict.

All the conflicts that are reported

You do not need to know these cases up front: the dialog’s message names the one that applies.

Conflict	Example	Message
Name already declared in the same scope (module, class, block, struct, package, or the project for modules, classes, packages)	rename a to b in a module that declares both; a struct field to another field’s name; module a to b when b.sv declares module b	'b' is already declared in this scope, 'b' is already declared in this struct, 'b' is already declared in b.sv
A usage would refer to something else: an inner declaration with the new name hides the renamed one	rename module signal a to b while block blk declares b and uses a	Usage of 'a' in 'a = 1;' would refer to another declaration of 'b'
An existing name would be captured: code that uses the new name today would start referring to the renamed declaration	rename a declared in block blk to b while the block uses module signal b	'b' in 'b = 1;' refers to another declaration and would be captured by the renamed 'a'
Import clash: a package item renamed to a name that an explicit import pkg::item; would bring into a scope that already declares it	rename p::y to x in a module with import p::y; and logic x;	'import p::y;' would import 'x' which clashes with the local declaration of 'x'
New override: renaming a method to the name of a virtual method of a base class, or so that a subclass method starts overriding it	rename d::g to f where base class base has virtual function void f()	Renaming to 'f' would override the virtual method 'f' of class base
Shared included file: a use in a file included in several places also means another declaration there	rename Width of ram_1p, where memload.svh, included by ram_1p and ram_2p, uses Width	'Width' in memload.svh also means the declaration in ram_2p.sv (the file is included in several places): renaming changes it there too
Macro formal: the new name is a formal of a macro whose body connects the port	rename the port clk_i to clk where `define FLOP(q, clk) prim_flop q (.clk_i(clk));	'clk' is a formal of macro FLOP in m.svh: its calls would replace the renamed name
New constraint override: renaming a constraint to the name of a base class’s constraint, or so that a subclass constraint starts overriding it	rename d::c_y to c_x where base class base has constraint c_x	Renaming to 'c_x' would override the constraint 'c_x' of class base
Wildcard connection: a port or signal connected implicitly by .* would be disconnected or connected differently	rename port clk of sub instantiated as sub u(.*);	Port 'clk' is connected implicitly with .* in 'sub u(.*);'; renaming it would disconnect the port
Library code: the rename would have to change a file attached as a library	rename build_phase in a class whose base class is in a library file base.sv	'build_phase' overrides a library method in base.sv which cannot be renamed
Duplicate definitions: the same name is also declared in another file and both will be renamed	rename module m defined in a.sv and b.sv	'm' is also declared in b.sv; usages refer to both, so both declarations will be renamed

If it doesn’t work

You see	Likely cause	What to do
No conflict dialog, and the rename just happens	The new name does not clash with anything the plugin can see	Check the result; undo with ⌘Z (Ctrl+Z)
A conflict you expect is not reported	The project is still indexing, the file is not in the project or not listed in its compile file (the .f list, such as sim.f in the sample project; see Conditional compilation), or the code is in an inactive `ifdef branch	See Conditional compilation and Known limitations
Rename is not offered	The caret is not on a name, or the name is declared by a macro (such as type_id)	Put the caret on a declaration; see Macros
The shortcut does nothing	Your keymap differs, or on a laptop you must hold Fn	Use Refactor | Rename…

See also Rename and Troubleshooting.