.. _External Builders:

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 3d 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.

.. _How to define a new external builder?:

How to define a new external builder
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Select the project in the **Navigator View**, right-click and choose **Properties**. Choose the **DVT > External Builders** properties. Click the **New** button to define a new external builder. From the list of external builders choose the generic External Builder or one of the pre-configured ones.

.. figure:: ../../images/vlogdt-external-builder-new-button.png

**Main tab**

.. figure:: ../../images/vlogdt-external-builder-main-tab.png

In the **Main tab** you can:

#.  Specify the **name** of the builder. It will appear in the extracted messages, for example in the **Errors View**.
#.  Specify the **Full Build command** - invoked on project full build and re-build. It is any regular shell command. You can use various variables (see pre-configured builders for examples).
#.  Specify the **Auto Build command** - invoked on incremental builds, for example on save. It is any regular shell command. You can use various variables (see pre-configured builders for examples).
#.  Specify the **Clean command** - invoked on project clean and before re-build. It is any regular shell command. You can use various variables (see pre-configured builders for examples).
#.  Specify the **working directory** where the commands are invoked from. You can use various variables, browse the file system etc. (see pre-configured builders for examples).
#.  Use various variables to pass as arguments to commands, for example ${incdir} or ${project_loc}.

.. note::

    If you wish to specify multiple commands or use wildcards or system variables, use sh -c "". E.g: sh -c "echo $USER; rm -f \*.log"

**Filters tab**

.. figure:: ../../images/vlogdt-external-builder-filters-tab.png

In the **Filters tab** you can:

#.  Choose from one of the predefined filter categories.
#.  Preview a filter.
#.  Define a new filter, edit, remove or duplicate an existing one. Filters in predefined categories cannot be edited or removed (allow future enhancements or fixes).

.. _How to invoke external builders:

How to invoke external builders
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. |d1| image:: ../../images/icons/act16/rebuild_ext.png
    :class: inline

External builders are automatically invoked after the DVT builder. For example when requesting to build or rebuild the project, when saving etc.  Obviously if the command is empty for a specific phase (full, clean or auto), the builder is not invoked.

You can also explicitly invoke only the external builders from the dedicated button |d1|.

The focus must be on some editor in the project or a resource from the project should be selected.

If you have multiple external builders defined for a project, you can select which one will be invoked by clicking on the respective entry in the menu:

.. figure:: ../../images/vlogdt-external-build-select-builder.png

.. note::
    
    When invoking only one builder, a **Clean Project** operation that removes all errors from all external builders is also triggered.

External Builder Output
~~~~~~~~~~~~~~~~~~~~~~~



An external builder dumps its output in the console upon invocation. Using the defined filters, matches are identified and hyper-linked to source code.

.. figure:: ../../images/vlogdt-vmm-smart-log.png



Source Code Markers - errors warnings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



The matches found in the builder output using the filters are marked on the source code. They are visible in the editors, Problems View etc.

You can :kbd:`Right+Click` on a marker to jump to the **Console** output of the external builder to investigate the error/warning.

.. figure:: ../../images/common/sv-external-builders-output.png



.. figure:: ../../images/common/sv-external-builders-jump-to-console.png



