.. _Basic Tutorial:

Basic Tutorial
==============

.. rst-class:: lead

   This tutorial provides a step by step walk-through of the SystemVerilog development environment.

Switch to the DVT Perspective
-----------------------------

The DVT Perspective provides a workbench layout with many useful views and shortcuts at hand for developing SystemVerilog code, for example the type browser, class hierarchy browser etc.

From menu :menuselection:`Window --> Open Perspective --> Other...` choose :guilabel:`DVT`

.. figure:: ../../images/common/dvt-open-perspective.png
   :align: center



You can customize and save a perspective. In order to further speed-up the development, at any time you can switch between various perspectives with different tool (views) layouts. For example you can use one perspective for writing code (the editor will take most of the real estate) and another perspective for code navigation (type browser will be a significant component).

The default DVT perspective looks like this:


.. figure:: ../../images/common/dvt-default-perspective.png
   :align: center


.. _Open a Project:

Open a Project
--------------

A **project** corresponds to a specific directory on the disk. The **project** is presented in the **Navigator View** - a file browser component that helps you browse the project directory contents.

.. seealso::
   
   :ref:`What is a Project`

Create a New Project
~~~~~~~~~~~~~~~~~~~~

Invoke the New Project Wizard: choose menu :menuselection:`File --> New --> DVT Project`.

.. figure:: ../../images/common/new-project-wizard.png
   :align: center



#.  **Specify the Project Directory** It can be a directory that already contains sources or a new directory that will be created.
#.  **Specify the Project Name** By default, the project's name is the last segment of the project's directory path (e.g. **/tmp/path1/path2/p_name > p_name**). You can change this name by selecting **Custom**.
    
    .. note:: 
      
      If **Project Directory** points to an existing project, you cannot change its name.
#.  **Open a Predefined Project** You may open one of the predefined projects that DVT ships with and continue to explore the DVT features. For more details see :ref:`Predefined Projects`.
#.  **Specify the Project Nature**. If the project does not exist or it does not contain any nature, you must select at least one nature. This way DVT will compile the respective sources.

Configure the Build
-------------------

In order to provide advanced functionality (like hyperlinks, autocomplete, design and class hierarchy, error signaling, etc.) DVT analyzes the source code files in your project. This analysis process is called build.

In order to build, DVT uses the arguments that you specify in one of the <name>.build files located in the .dvt folder of your project.

The default build configuration is .dvt/default.build. Here you list compilation directives in a similar way you would pass arguments to any simulator.

When a project is created using the New DVT Project Wizard, the default build configuration file contains the +dvt_init_auto directive, that triggers the DVT auto-config mechanism. For more details, see :ref:`Auto-config`.

The DVT auto-configuration algorithm automatically detects and analyses existing Intel(Altera) Quartus or Xilinx ISE/Vivado projects in the project root directory to generate a build configuration. For more details, see  :ref:`FPGA Support`.

If no source code files are found for compilation, you'll be notified there is nothing to build.

.. figure:: ../../images/common/no-default-build.png
   :align: center


To configure the build **follow the link** in the build notification dialog or open the **.dvt/default.build** file.

.. seealso::
   
   :ref:`Build Configurations`.

Build the Project
-----------------

.. |rebuild-icon| image:: ../../images/icons/act16/rebuild.png
   :class: inline

Once you specified the files you want to compile, the incdirs to be used for \`include and so on, you should rebuild the project. In general, every time you change the .build configuration, you should rebuild.

In order to rebuild you click the **Rebuild button** |rebuild-icon|.

While editing source files, a project is incrementally compiled as soon as you save, unless the menu option :menuselection:`Project --> Build Automatically` is un-checked.

The building progress is reported in the :guilabel:`Progress View`. Depending on your configuration, you may also see detailed information in the :guilabel:`Console View`.

.. figure:: ../../images/vlogdt-get_started-buid-progress.png
   :align: center

Inspect the Compilation Errors
------------------------------

Syntax errors are detected as you type.

.. figure:: ../../images/vlogdt-syntax-error-marker.png
   :align: center

They are indicated in the vertical bars of the editor (right - for the visible code, left - for the full file). If you **keep the mouse over the marker** on the left you'll see more details about the error.

.. figure:: ../../images/vlogdt-syntax-error-info.png
   :align: center

Same tooltip will appear if you keep the mouse over the marker on the editor right bar. You can also **click on the marker** to jump to the error.

.. figure:: ../../images/vlogdt-syntax-error-info_right.png
   :align: center

If a project contains errors, for example syntax errors, it will be indicated using **decorators**:


.. figure:: ../../images/vlogdt-errors-decorator.png
   :align: center

You can use the :guilabel:`Problems View` to inspect the errors. You can show the Problems View from menu :menuselection:`Window --> Show View --> Other... --> General --> Problems`. **Double clicking** on some error will jump to the source location.

.. figure:: ../../images/vlogdt-errors-view.png
   :align: center

See Comments in Tooltips
------------------------

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

Some examples are presented below. In a similar way you'll see information on fields, events, variables etc., predefined or not.

.. list-table::
   :widths: 10 90
   :header-rows: 0
   :stub-columns: 1
   :align: center

   * - Type Info
     - .. figure:: ../../images/vlogdt-tooltip-type-info.png
        :align: center

   * - Macro Info
     - .. figure:: ../../images/vlogdt-tooltip-macro-info.png
        :align: center

   * - Task Info
     - .. figure:: ../../images/vlogdt-tooltip-task-info.png
        :align: center

The information presented in the tooltip is created using the comment on top of the declaration.

For example, given the following declaration of a field:


.. figure:: ../../images/vlogdt-field-declaration-for-tooltip.png
   :align: center


the corresponding tooltip will look like this:


.. figure:: ../../images/vlogdt-tooltip-field-info.png
   :align: center


Use Hyperlinks to Move Around in the Code
-----------------------------------------

If you **place the mouse over** a type, method, field etc. and press the :kbd:`Ctrl` key, a hyperlink will be presented. :kbd:`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
   :align: center

You can hyperlink and jump to an imported file.

.. figure:: ../../images/vlogdt-hyperlink-to-file.png
   :align: center


You can hyperlink and jump to a macro.

.. figure:: ../../images/vlogdt-hyperlink-to-macro.png
   :align: center

Quickly Open a Type (Class, Module, Interface)
----------------------------------------------

You can quickly open a specific type definition. Press :kbd:`Ctrl+Shift+T`.

The Quick Types View will pop-up and you can enter any regular expression to locate a type. Select and press :kbd:`Enter` or :kbd:`Click` to jump to its definition.

.. figure:: ../../images/sv_quick_types_view.png
   :align: center


Quickly Inspect the Class Hierarchy
-----------------------------------

You can quickly see inheritance tree for a class, task, function etc. Put the cursor over the entity name and press :kbd:`Ctrl+T`.

.. figure:: ../../images/sv_quick_type_hierarchy_view.png
   :align: center


For example for functions you can also see the implementations along the hierarchy (icons are not grayed).

.. figure:: ../../images/sv_quick_type_hierarchy_view_method.png
   :align: center


Quickly Open a File
-------------------

You can quickly open a file that is included via the top files. Just press :kbd:`Ctrl+I`.The 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/sv_quick_compile_order_view.png
   :align: center

You can also 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/sv_compile_order_view.png
   :align: center

   This is the Compile Order View.

Quickly Move Inside the Editor
------------------------------


Press :kbd:`Ctrl+O` to open the Quick Outline for an overview of your file. You can enter any regular expression to locate an entity to jump to the current file.

.. figure:: ../../images/vlogdt-quick-outline-view.png
   :align: center


You can also see the outline in the :guilabel:`Outline View`. Open the view from menu :menuselection:`Window --> Show View --> Other... --> General --> Outline`.

.. figure:: ../../images/vlogdt-outline-view-presentation.png
   :align: center


Inspect the Class Hierarchy and Class Members
---------------------------------------------

Position the cursor on the relevant name and press :kbd:`F4` or :kbd:`right click` and choose :menuselection:`Show --> Type Hierarchy` from the menu.

The :guilabel:`Type Hierarchy View` will present:

-  the inheritance tree (for example parents and children of a class)
-  members

.. figure:: ../../images/sv_type_hierarchy_view.png
   :align: center



Inspect the Design Hierarchy
----------------------------

Position the cursor on a module name and press :kbd:`Shift+F4` or :kbd:`right click` and choose :menuselection:`Show --> Design Hierarchy` from the menu.

The :guilabel:`Design Hierarchy View` opens with the chosen element set as the top of the hierarchy.

.. figure:: ../../images/common/design-hierarchy-presentation.png
   :align: center


Inspect the Verification Hierarchy
----------------------------------

Position the cursor on a UVM class name and press :kbd:`Shift+F6` or :kbd:`right click` and choose :menuselection:`Show --> Verification Hierarchy` from the menu.

The :guilabel:`Verification Hierarchy View` opens with the chosen class set as the top of the hierarchy.

.. figure:: ../../images/common/sv-verification-hierarchy-presentation.png
   :align: center

Browse Through All the Available Types (Classes, Modules, Interfaces)
---------------------------------------------------------------------

You can explore all the types like classes, modules, interfaces or structs... that are defined in your project using the :guilabel:`Types View`.

Go to menu :menuselection:`Window --> Show View --> Other... --> DVT --> Types` to open the :guilabel:`Types View`.

.. figure:: ../../images/sv_types_view.png
   :align: center


Look for the Implementation of an Extern Function or Task
---------------------------------------------------------

Position the cursor on the relevant name and press :kbd:`Shift+F3` or :kbd:`right click` and choose :menuselection:`Show --> Layers` from the menu.

.. figure:: ../../images/sv_layers_view.png
   :align: center



Search for Entities
-------------------

You can search for a specific type, method etc. in the current project or whole workspace. Press :kbd:`Ctrl+H` to pop-up the search dialog.

.. figure:: ../../images/vlogdt-search-dialog.png
   :align: center


The results are presented in the :guilabel:`Search View`.

.. figure:: ../../images/vlogdt-search-view.png
   :align: center




Use Content Assist (Autocomplete)
---------------------------------

Content assist provides you with a list of suggested completions for partially entered text. Proposals are context dependent and include accessible fields, methods, variables, OVM macros etc. as well as templates for various constructs.

Press :kbd:`Ctrl+Space` to trigger content assist.

Content assist is triggered automatically in some contexts, for example when you type in a **.** (dot) in the editor after a class type field name.

Proposals are presented in a list for you to choose from. Moving through proposals you can quickly see the related documentation.

Press :kbd:`Enter` or :kbd:`click` to select a proposal or :kbd:`Esc` to cancel the assist.

.. figure:: ../../images/vlogdt-content-assist-example-1.png
   :align: center


.. figure:: ../../images/vlogdt-content-assist-example-2.png
   :align: center


.. figure:: ../../images/vlogdt-content-assist-example-3.png
   :align: center



Use Code Templates
------------------

When you trigger autocomplete using :kbd:`Ctrl+Space`, template suggestions may appear in the proposal list.

.. figure:: ../../images/common/global-code-templates-sv-proposal.png
   :align: center




To define templates go to the :menuselection:`DVT --> Code Templates` preference page (via menu :menuselection:`Window --> Preferences`) and select **SystemVerilog** from :guilabel:`Select Nature`.

.. figure:: ../../images/common/global-code-templates-pref-page.png
   :align: center


Click the :guilabel:`New` button to define a new template. The template name is important for proposal filtering based on already typed text.

.. figure:: ../../images/common/code-templates-edit-template.png
   :align: center


Use Module Auto Instance
------------------------

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.

You can customize what gets generated from menu :menuselection:`Window --> Preferences --> DVT --> SystemVerilog --> Editor --> Content Assist` in the Auto-instantiation section.

.. figure:: ../../images/sv-module-auto-instantiation.png
   :align: center


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 :kbd:`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
   :align: center


To expand them in a temporary file, choose **Expand One Level** or **Expand All Levels**.

.. figure:: ../../images/vlogdt-expand-macros-file.png
   :align: center

.. 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
   :align: center


-  or **selecting** the error in the Problems View, :kbd:`right click` and choosing :guilabel:`Macro Trace`

.. figure:: ../../images/vlogdt-macro-trace-action2.png
   :align: center




The macro error trace will be presented in the :guilabel:`Console View` with hyperlinks to source.

.. figure:: ../../images/vlogdt-macro-trace-console.png
   :align: center


.. _Track Tasks using TODO Markers:

Track Tasks using TODO Markers
------------------------------


If you place TODO markers in your code they are recognized and presented in the :guilabel:`Tasks View`. This is a mean to insert reminders, preserve, track and share them with your team.

You can use TODO markers inside comments. **FIXME** (high priority), **TODO** and **XXX** (low priority) are recognized.

Go to menu :menuselection:`Window --> Show View --> Other... --> General --> Tasks` to open the :guilabel:`Tasks View`.

**Double click** on a task to jump to the marker definition.

.. figure:: ../../images/vlogdt-reminders-CodeTasksView.png
   :align: center


Quickly See the Current Scope in the Status Bar
-----------------------------------------------

The scope at cursor (current function/class/module...) is always presented in the **status bar**.

.. figure:: ../../images/common/sv-current-scope.png
   :align: center


Fold Code Regions in Order to Improve Readability
-------------------------------------------------

.. |expand-icon| image:: ../../../../../common/images/generic_icons/expand_tree.png
    :class: inline

.. |collapse-icon| image:: ../../../../../common/images/generic_icons/collapse_tree.png
    :class: inline

Use the :guilabel:`Expand All` |expand-icon| button or the :guilabel:`Collapse All` |collapse-icon| button from the toolbar or from right click menu :menuselection:`Source --> Folding` to unfold/fold the current file.

.. figure:: ../../images/vlogdt-collapsed-code.png
   :align: center

.. _Access the Context Sensitive Help:

Access the 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. :kbd:`F1` key on Windows, :kbd:`Ctrl+F1` on GTK, Help key on Carbon):


.. figure:: ../../images/common/sv-outline-context-help.png
   :align: center

