.. _Tips and Tricks:

Tips and Tricks
===============


The following tips and tricks give some helpful ideas for increasing your productivity.

.. |mark-occurrences| image:: ../../images/icons/act16/mark_occurrences.png
  :class: inline

.. |overrides-indication| image:: ../../images/vlogdt-override-function-indication.png
  :class: inline

Editing
-------

.. list-table::

   * - Content assist
     - Content assist provides you with a list of suggested completions for partially entered text. In the editor press :kbd:`Ctrl+Space`.  

       .. figure:: ../../images/vlogdt-content-assist-example-1.png
   * - Module Automatic Instantiation
     - You need to type the first letters of the module name, then press :kbd:`Ctrl+Space` three (3) times.You can recognize module instances by their icon, it looks like a chip with ports ready to be glued in.  

       .. figure:: ../../images/sv-module-auto-instantiation.png
   * - Expand Macros (Apply Preprocessing)
     - You can apply preprocessing over a selected section of code in order to see how macros are expanded. You have multiple options in the right-click context menu Macros. To expand them in the source file, choose **Expand One Level Inline** or **Expand All Levels Inline**.

       .. figure:: ../../images/sv-expand-macros-inline.png
        
       To expand them in a temporary file, choose **Expand One Level** or **Expand All Levels**.

       .. figure:: ../../images/vlogdt-expand-macros-file.png
       
       .. note::
          
          You can also expand all macros in the current file by selecting either **Expand All Macros Inline**, for expansion in the source file, or **Expand All Macros**, for expansion in a temporary file. 
   * - Trace Macro Errors
     - To debug macro usage errors (especially if macros in macros are used) you can see how the error is propagated from macro to macro (the error trace) either by:  
     
       - going with the mouse over the error marker on the left and **right click**  

       .. figure:: ../../images/vlogdt-macro-trace-action1.png  
        
       - or selecting the error in the :guilabel:`Problems View`, **right click** and choosing :guilabel:`Macro Trace` 

       .. figure:: ../../images/vlogdt-macro-trace-action2.png   
        
       The macro error trace will be presented in the :guilabel:`Console View` with hyperlinks to source.   

       .. figure:: ../../images/vlogdt-macro-trace-console.png
   * - Code templates
     - Code templates are presented in content assist if applicable.  

       .. figure:: ../../images/common/global-code-templates-sv-proposal.png
   * - Matching begin - end
     - If you **double click** on/after begin – end, function – endfunction etc. the block is highlighted.   

       .. figure:: ../../images/vlogdt-matching-begin-end.png
   * - Mismatched endif
     - You can use comments after endif to track the match with starting ifdef. If the name of ifdef doesn't match the endif comment a warning is issued.   

       .. figure:: ../../images/vlogdt-mismatched-endif.png
   * - Toggle Comment
     - You can toggle comment on/off for the current line or the selected lines. Press :kbd:`Ctrl+/` or use the action from the drop down menu on right click in editor.   

       .. figure:: ../../images/vlogdt-toggle-comment.png
   * - Expand/Restore Selection
     - Press :kbd:`Shift+Alt+Up` Arrow to incrementally expand the current selection. For example when the cursor is on a word, select the word. Press again to select the whole line. Then, each of the nested enclosing scopes is selected, for example ``begin...end``, then the enclosing function, then the enclosing class and so on. The same principle applies to nested enclosing parentheses, brackets and curly braces, as well as strings.  Press :kbd:`Shift+Alt+Down` Arrow to restore the previous selection step made with :kbd:`Shift+Alt+Up` Arrow
   * - Format source
     - Use the :menuselection:`Source --> Format Source` action from the editor's right click menu. The whole file is formatted or the current selection, if any.
   * - Override functions
     - To access the Override menu, in Editor, **right click** inside a class body > Source > Override Methods.
   * - One key indentation
     - If you press :kbd:`Tab` once at the beginning of a line, it is automatically aligned to the enclosing context. Press twice to insert a tab.
   * - Reminders (TODO markers)
     - When you tag a comment in source code with **TODO**, a corresponding tasks is automatically created as a reminder. From the :guilabel:`Tasks View`, **double click** on the task takes you to the **TODO** in the code. Same for for **FIXME** (higher priority) and **XXX** (lower priority) markers. You can also add your own tags, see the :ref:`Reminders (TODO Markers)` section of the documentation. 

       .. figure:: ../../images/vlogdt-reminders-CodeTasksView.png
   * - Spell checking
     - You can enable spell-checking support from the :menuselection:`General --> Editors --> Text Editors --> Spelling` preference page. Spelling errors are displayed in the Verilog Language editor and corresponding Quick Fixes are available.   

       .. figure:: ../../images/vlogdt-spelling-correction-proposal.png
   * - Folding
     - You can fold code sections to improve read-ability. This is how a folded file looks like:  

       .. figure:: ../../images/vlogdt-collapsed-code.png   
        
       Folding actions (to expand or collapse) are available in the toolbar 

       .. figure:: ../../images/common/dvt-collapse-expand-buttons.png 
        
       or on **right click** in the editor. You may also use the **+** or **-** signs on the left side of the editor.   
       
       - Use **Collapse All Levels** for folding to statement (class, module ...) level.   
       - Use **Show First Level** for folding to struct member (method, cover...) level.  
       - Use **Expand All** to fully expand the file.

       When you type on a folded line, it is automatically expanded. You may see the folded code in a tooltip if you move with the mouse over the **+** sign.
   * - Folding custom areas
     - You can define custom folding areas using comments to indicate the start and the end of the area:  

       .. figure:: ../../images/common/dvt-custom-folding.png
   * - Maximize editor
     - **Double-click** on the editor tab to maximize editor to full window. **Double-click** again to restore.
   * - Show line numbers
     - Check :guilabel:`Show line numbers` from the :menuselection:`General --> Editors --> Text Editors` preference page
   * - Local history
     - Whenever you edit a file, its previous contents are kept in the local history. **Right click** in the editor and choose :menuselection:`Compare With/Replace With --> Local History...`   

       .. figure:: ../../images/vlogdt-local-history.png
   * - Inactive code highlight
     - The editor marks with a colored background the areas of code that are not compiled due to preprocessing. See the :ref:`Inactive Code Highlight` documentation section.    

       .. figure:: ../../images/vlogdt-macros-inactive-code-highlight.png
   * - Emacs Automation
     - You can invoke Emacs to perform automation on the file you are currently editing. In the editor window: Right click > Source > Emacs, then select one of: Auto, DeleteAuto, InjectAuto, Indent or use the associated key bindings (the same as in Emacs).
       
       .. note::
          The shortcuts are available only when Emacs mode is enabled in Eclipse; to enable Emacs mode go to :menuselection:`Window --> Preferences --> General --> Keys` and select the Emacs scheme.
       
       .. note::
          You can also add toolbar buttons to perform Emacs automation: go to :menuselection:`Window --> Customize Perspective --> Command Groups Availability` and check Emacs Verilog-Mode from the Available command groups on the left.
       
       .. note::
          To change the default emacs command go to :menuselection:`Window --> Preferences --> DVT` and fill in the Emacs command you want to execute.
   * - Open file in more editors
     - To open multiple editors for the same file you should first open the file then **right click** on the editor's titlebar and select New Editor  

       .. figure:: ../../images/vlogdt-tips-new-editor.png
   * - Split the editor view
     - To open multiple editors side by side follow these steps:    
       
        - open each file in its editor; if you wish to see the same file in a split view, **right click** on its titlebar and select New Editor  
        
        - if you wish to split horizontally, drag the title bar of the file you want to split and drop it over the horizontal scrollbar    

        .. figure:: ../../images/vlogdt-tips-split-editor-horizontal.png  
        
        - if you wish to split vertically, drag the title bar of the file you want to split and drop it over the vertical scrollbar  

        .. figure:: ../../images/vlogdt-tips-split-editor-vertical.png
   * - Column selection
     - You can switch to and from column (block) selection mode either by clicking on the “Toggle Block Selection Mode” button in the toolbar, or by using the :kbd:`Shift+Alt+A` shortcut key.  

       .. figure:: ../../images/common/dvt-toggle-block-selection.png
   * - Auto insert JavaDoc comment
     - To add JavaDoc like comments to code, in Code Editor type above the code declaration /** and then press :kbd:`Enter`. Depending on the code type (a class declaration, a function, a task etc.) a comment will be added with the respective JavaDoc tags. For more details: :ref:`Export HTML/PDF Documentation`

       .. figure:: ../../images/vlogdt-javadoc-templates-custom-result.png


Code Navigation
---------------


.. list-table::

   * - Tooltips
     - When you position the mouse over a type, method, field etc., a tooltip will pop-up showing information on corresponding declaration.  

       .. figure:: ../../images/vlogdt-tooltip-type-info.png  

       .. figure:: ../../images/vlogdt-tooltip-macro-info.png  

       .. figure:: ../../images/vlogdt-tooltip-task-info.png
   * - Hyperlinks
     - If you place the mouse over a type, method, field, macro etc. and press the :kbd:`Ctrl` key, a hyperlink will be presented. **Click** on the hyperlink to jump to definition.
       
       You can also jump to a definition if you put the cursor on the relevant name and press :kbd:`F3` .

       .. figure:: ../../images/vlogdt-hyperlink-to-field.png
   * - Inheritance tree and members (Type Hierarchy View)
     - You can view the inheritance tree and all the members of a class by placing the mouse over it and pressing the :kbd:`F4` key.  

       .. figure:: ../../images/sv_type_hierarchy_view.png
   * - Design hierarchy of a module (Design Hierarchy View)
     - You can view the design hierarchy of a module by placing the mouse over it and pressing :kbd:`Shift+F4`.  

       .. figure:: ../../images/common/design-hierarchy-presentation.png
   * - Class Diagrams
     - You can create class diagrams to inspect or document the architecture of a verification environment. For more details see the :ref:`Class Diagrams <UML Diagrams>`
   * - Current Scope
     - The scope at cursor (function/class...) is always presented in the status bar.  

       .. figure:: ../../images/vlogdt-current-scope.png
   * - Quick Type
     - You can quickly open a specific type definition. Press :kbd:`Ctrl+Shift+T`.
     
       The :guilabel:`Quick Types View` will pop-up and you can enter any regular expression to locate a type. Select and press :kbd:`Enter` or **click** to jump to its definition.  

       .. figure:: ../../images/common/quick-types-view.png
   * - Quick Outline
     - Press :kbd:`Ctrl+O` to open the Quick Outline for an overview of your file. You can enter any regular expression to locate a place to jump in the current file.  

       .. figure:: ../../images/vlogdt-quick-outline-view.png
   * - Quick Compile Order
     - You can quickly open a file that is included via the top files. Just press :kbd:`Ctrl+I`. The :guilabel:`Quick Compile Order View` will pop-up and you can enter any regular expression to locate a file. Select and press :kbd:`Enter` or **click** to open the file.  

       .. figure:: ../../images/common/quick-compile-order-view.png
   * - Quick Type Hierarchy
     - Position the cursor on the entity (struct, method ...) name and press :kbd:`Ctrl+T` to see the :guilabel:`Quick Type Hierarchy View`.  

       .. figure:: ../../images/sv_quick_type_hierarchy_view.png  
        
        For methods and others, non-grayed icons means parent implementations are available.  

       .. figure:: ../../images/sv_quick_type_hierarchy_view_method.png
   * - External Implementation
     - You can view the external implementations in the :guilabel:`Layers View`. Position the cursor on the relevant name and press :kbd:`Shift+F3` or **right click** and choose :guilabel:`Show Layers` from the menu.  

       .. figure:: ../../images/sv_layers_view.png
   * - Types View
     - You can view all the types (scalars, classes, module) in the project (including their fields, methods etc.) in the :guilabel:`Types View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> DVT --> Types`.  

       .. figure:: ../../images/sv_types_view.png
   * - Checks View
     - You can view all the checks (immediate, concurrent, deferred immediate assert and assume constructs) in the project in the :guilabel:`Checks View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> DVT --> Checks`.

       .. figure:: ../../images/vlogdt-checks-view.png
   * - Coverage View
     - You can browse all the coverage definitions in the project using the :guilabel:`Coverage View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> DVT --> Coverage`.

       .. figure:: ../../images/vlogdt-coverage-view.png
   * - Compile Order View
     - You can see the include tree of the files in your project in the :guilabel:`Compile Order View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> DVT --> Compile Order`.  

       .. figure:: ../../images/common/compile-order-view-presentation-orig.png
   * - Macros View
     - You can see all the macros in your project in the :guilabel:`Macros View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> DVT --> Macros`.  

       .. figure:: ../../images/sv_macros_view.png
   * - Outline View
     - You can see the summary contents of the current file (structs, field, methods) in the :guilabel:`Outline View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> General --> Outline`.  

       .. figure:: ../../images/vlogdt-outline-view-presentation.png
   * - Mark occurrences
     - When working in the SystemVerilog editor, turn on Mark Occurrences in the toolbar |mark-occurrences| or press :kbd:`Alt+Shift+O`.  

       .. figure:: ../../images/vlogdt-occurrences-highlighted.png
   * - Override Annotations
     - Override Annotations indicate that a function/task overrides a parent class implementation. |overrides-indication|
   * - Bookmarks
     - Similar with a web browser, you can add bookmarks in your code without altering the code. **Right click** on the left vertical bar of the editor and choose :guilabel:`Add Bookmark...`  

       .. figure:: ../../images/vlogdt-bookmark-action.png  
        
        Specify a meaningful name:  

       .. figure:: ../../images/vlogdt-bookmark-dialog.png  
        
        You can jump to bookmarks from Bookmarks View. Open the view from menu :menuselection:`Window --> Show View --> Other... --> General --> Bookmarks`.

       .. figure:: ../../images/vlogdt-bookmarks-view.png
   * - Go to line
     - Press :kbd:`Ctrl+L` shortcut or **double click** in the status bar to jump to a specific line.  

       .. figure:: ../../images/common/dvt-line-number-in-status-bar.png  

       .. figure:: ../../images/common/dvt-go-to-line.png
   * - Back/Forward navigation
     - You can navigate between editors in a browser like way using the Back/Forward Navigation 

       .. figure:: ../../images/common/dvt-back-forward-buttons.png
   * - Go to last edit location
     - Useful when you navigated around in the code, before proceeding with the source change. **Click** on Last Edit Location button 

       .. figure:: ../../images/common/dvt-last-edit-location-button.png 
        
       in the toolbar to jump to the file where you were previously editing.


Searching
---------

.. list-table::

   * - Search for task. function, field etc.
     - To search for the declaration of a specific type, method, field etc.:
      
       - Press :kbd:`Ctrl+H` to open the Search Dialog
       - Click on the :guilabel:`Verilog Search` tab.
       - Type the name in the Search String (if you select in the editor before pressing :kbd:`Ctrl+H`, the Search String is automatically set to the selection).
       - Select type or function etc. and Declarations
       - Click Search.  

       .. figure:: ../../images/vlogdt-search-dialog.png
   * - Search for references
     - To search where a method (or field etc.) is used, hold :kbd:`Ctrl`, hover over its name and select :guilabel:`Show Usages` or **right click** on its name > Show > Usages or **right click** on its name > References > Project. The results are presented in the :guilabel:`Search View`. You can also search for references from the Search Dialog (:kbd:`Ctrl+H`).  

       .. figure:: ../../images/vlogdt-right-click-references.png
   * - Search for whole word
     - To search for a whole word in all files, in comments or not:
      
       - Press :kbd:`Ctrl+H` to open the Search Dialog
       - Click on the :guilabel:`Verilog Search` tab.
       - Type the name in the Search String (if you select in the editor before pressing :kbd:`Ctrl+H`, the Search String is automatically set to the selection).
       - Select :kbd:`Whole Word` and :kbd:`Do not search in comments` or :kbd:`All occurrences`
       - Click Search.

       .. figure:: ../../images/vlogdt-search-whole-word.png


Miscellaneous
-------------


.. list-table::

   * - All shortcuts
     - Press :kbd:`Ctrl+Shift+L` to see all shortcuts.

       .. figure:: ../../images/common/dvt-all-shortcuts.png
   * - Project Properties
     - Select the project in the :kbd:`Navigator View`, **right click** and choose :guilabel:`Properties`. Or from menu :menuselection:`Project --> Properties`.
   * - OVM Field Editor
     - The OVM Field Editor enables you to inspect and edit OVM field registrations. To bring up the OVM Field Editor, **right click** inside a class definition and select :guilabel:`OVM Field Editor` from the pop-up menu, or simply press :kbd:`Shift+Alt+F`.   

       .. figure:: ../../images/vlogdt-ovm-fieldeditor-simple.png
   * - UVM Field Editor
     - The UVM Field Editor enables you to inspect and edit UVM field registrations. To bring up the UVM Field Editor, **right click** inside a class definition and select :guilabel:`UVM Field Editor` from the pop-up menu, or simply press :kbd:`Shift+Alt+G`.   

       .. figure:: ../../images/vlogdt-uvm-fieldeditor-simple.png
   * - Project templates
     - A project template is a parameterized directory tree. Both in the file contents (.v, .sv, .sh - practically any file) and in the file or directory names you can use parameters. Combined with **TODO** markers, you can use a project template as a customized wizard. For more details see the :ref:`Project Templates` chapter in VlogDT User Guide.
   * - System Variables and -f Support
     - See: :ref:`Build Configurations`
   * - Generic launch (make, scripts etc.)
     - You can launch external scripts: Menu Run > Run.... Select DVT Generic configuration and click the New button. Specify name, working directory and command. Click Run.   

       .. figure:: ../../images/vlogdt-launch-generic-dialog.png  
        
        You can also use the Run > Quick Run menu (or Ctrl+U shortcut key) to quickly launch any existing Run Configuration:  

       .. figure:: ../../images/common/dvt-run_configurations-quick_run_menu.png
   * - Create dialogs for scripts & flows
     - You can create :ref:`Custom Dialogs` for your own scripts:  

       .. figure:: ../../images/common/dvt-customdialogs-demo.png  
        
       Follow the wizard from menu New > Example > DVT > DVT Custom Dialog, then create a run configuration with the command ``echo ${dvt_dialog_prompt:customdialog.swtxml}`` and run it.
   * - Open terminal
     - You can open a fully working command-line terminal inside of DVT: In the Navigator View right-click on the desired location and select Open Terminal Here
   * - External Builders
     - An external builder allows you to invoke any script/tool and back-annotate its output (errors, warnings etc.) to the source code. It is a mean that allows you to connect any 3rd party tool (compiler, linter etc.) to DVT error signaling engines. You can configure one or more external builders on a project:
       
       * The commands you define will be invoked on project clean, full build and incremental build.
       * The patterns you define will be applied on the command output to recognize errors, warnings etc.
       * The pattern matches will be back-annotated to the source code and presented in a similar way DVT signals errors (file, line, in the Errors View etc.) DVT ships with some predefined example configurations to get you started. For more details see the :ref:`External Builders` chapter in VlogDT User Guide.
   * - External Documentation
     - You can browse and search through 3rd party documentation using the Eclipse help system. For more details see the :ref:`External Documentation` chapter in VlogDT User Guide.
   * - Context Sensitive Help
     - A focused set of help topics that is related to the current context can be shown to users on demand using context-sensitive help. This form of user assistance is delivered to users when a platform-specific trigger is activated (e.g. F1 key on Windows, Ctrl+F1 on GTK, Help key on Carbon). For more details see the :ref:`Context Sensitive Help <Access the Context Sensitive Help>` chapter in VlogDT User Guide.  

       .. figure:: ../../images/vlogdt-context-sensitive-help.png
   * - Mapping Linux to Windows
     - Linux directories can be mapped to Windows drives, thus allowing editing files from Windows. For example /home/simi is mapped to Z:\. This has an impact on paths configured for a DVT project, for example INCDIRs etc. The paths are set using Linux conventions, however Eclipse runs in Windows and the DVT builder needs to know about the mapping in order to compile the files.  To specify the mapping, set the system variable %DVT_CROSSPLATFORM_MAP% before invoking Eclipse. You can add multiple mappings separated by ";" e.g.:  /projects/=p:\;/home/lars/=Z:\lars\
   * - Recover from abnormal inconsistencies
     - In the event of unexpected behavior (missing results in search, types in type browsing, hyperlinks, tooltips etc.) please manually trigger a clean build from menu Project > Clean....
   * - OVM Smart Log
     - DVT ships with predefined filters for OVM that allow you to view colored and hyper-linked logs like the one below:   

       .. figure:: ../../images/vlogdt-ovm-smart-log.png 
        
       See :ref:`OVM Smart Log` for more details.
   * - UVM Smart Log
     - DVT ships with predefined filters for UVM that allow you to view colored and hyper-linked logs like the one below:  

       .. figure:: ../../images/vlogdt-uvm-smart-log.png  
        
       See :ref:`UVM Smart Log` for more details.
   * - OVM to UVM Migration
     - DVT provides an OVM to UVM migration wizard that automatically performs all the necessary changes within an existing OVM project. To start the wizard: right click on a project/file/directory in the navigator, then select Refactor > Migrate OVM to UVM. See :ref:`OVM to UVM Migration` documentation page for more details.
   * - Add a new file extension to compile list extensions
     - Go to Window > Preferences > General > Content Types, select a category from the list (for example Verilog Source File) then click on Add and then on Ok. 

       .. figure:: ../../images/vlogdt-contenttype-add-file-extension.png
   * - Sharing workspace settings
     - Export all Workspace/ Eclipse customization:   - Go to File > Export > General > Preferences    - Make sure Export all is selected  - Select a file where the preferences should be exported     Now you can share this file with your team. When it is imported into another instance of Eclipse (by using File > Import > General > Preferences), the configuration (all options available in Window > Preferences) is replaced by the imported one.  Note: you should restart Eclipse for the changes to be enforced (File > Restart). 

       .. figure:: ../../images/common/export-preferences-select.png 

       .. figure:: ../../images/common/export-preferences-exportall.png
   * - Using System Variables in Linked Resources
     - You can use System Variables in the path of linked resources. For example ${DVT_ENV-SYSTEM_VARIABLE_NAME}/work is equivalent to $SYSTEM_VARIABLE_NAME/work in a console.
   * - Waive problems reported by DVT
     - You can use :ref:`Compile Waivers` to promote, demote or disable the problems reported by DVT.

       To quickly create a new waiver, in the :ref:`Problems View` right click on any problem reported by DVT and waive it. DVT proposes some default values for the waiver description, path and message. You can easily change them to fine-tune the waiver.

       To quickly start up a new waivers file click on the Edit waivers button in the Problems View. The **.dvt/waivers.xml** is created with a default content and opened. You can easily create your own waivers from the default generated ones.

       In the waivers editor you can use autocomplete for tags, attributes and attribute values.
   * - Open a file in DVT from the terminal
     - You can use the :ref:`Command Line Interface` like this: 
       
       .. code-block::
       
          $> dvt_cli.sh -workspace ~/dvt_workspace openFile $(readlink -f my/file.sv)
       
       The command can be shortened by defining this alias in your ~/.cshrc: 
      
       .. code-block::
          
          alias dvtopen 'dvt_cli.sh -workspace ~/dvt_workspace openFile `readlink -f \!*`'
       
       or by defining this function in your ~/.bashrc: 
       
       .. code-block::
       
          dvtopen () { dvt_cli.sh -workspace ~/dvt_workspace openFile $(readlink -f $1); }
          
       Then the command gets much shorter: 
       
       .. code-block::
       
          $> dvtopen my/file.sv
