.. _External Builders:

External Builders
=================

.. rst-class:: lead

	An external builder allows you to invoke any script/tool and back-annotate its output (errors, warnings etc.) to the source code. Practically it 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 :menuselection:`DVT --> External Builders` properties. Click the :guilabel:`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/edt-external-build_config1.png
	:align: center




**Main tab**

.. figure:: ../../images/edt-external-build_config-props_main.png
	:align: center




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::
	
	To specify multiple commands use **sh - c "..."**


**Filters tab**

.. figure:: ../../images/edt-external-build_config-props_filter.png
	:align: center




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 configure a filter?:

How to configure a filter?
~~~~~~~~~~~~~~~~~~~~~~~~~~



.. figure:: ../../images/edt-external-build_config-new_filter.png
	:align: center




You can:

#. Specify the **name**.
#. Specify the **severity**.
#. Specify the **description**.
#. Specify the **matching pattern**. Special variables are used to extract from the matched text the **error location (${file} and ${line}) and the error message(${message})**.
#. Insert special variables mentioned above. Autocomplete in the pattern text-box is also available.
#. **Enable/disable** the filter.

.. _How to invoke external builders:

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



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.

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

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

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 invoke a specific one by clicking on the respective entry in the menu:

.. figure:: ../../images/edt-external-build-select-builder.png
	:align: center




.. note::

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


.. _External Builder Output:

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/edt-external-builder-output.png
	:align: center



.. _Source Code Markers - errors warnings:

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 **right-click** on a marker to jump to the **Console** output of the external builder to investigate the error/warning.

.. figure:: ../../images/edt-external-builder-editor.png
	:align: center




.. figure:: ../../images/edt-external-builder-errors-view.png
	:align: center




.. figure:: ../../images/common/e-external-builders-jump-to-console.png
	:align: center




