.. _Run Configurations:

Run Configurations
==================


You can invoke (run) any executable from Eclipse and see its output in the **Console View**.

You just need to create a **Run Configuration** from menu :menuselection:`Run --> Run...`.

VhdlDT provides one type of configuration:

- DVT Generic

**DVT Generic Run Configuration**

#.  Menu :menuselection:`Run --> Run Configurations...`.
#.  Select :guilabel:`DVT Generic` configuration and click the :guilabel:`New` button.
#.  Specify **name, working directory, run as command or script and the content of the command or script**.
#.  Click :guilabel:`Run`.

.. figure:: ../../images/common/dvt-run_configurations-dialog_1.png
	:align: center




Before writing the command you can specify how to run the content. Run as a:

-  command: the content must be a single line command with arguments
-  script: the content must be a multiline script, preceded by a hash exclam; in Windows the script will run using cmd.exe, if a *#!/bin/sh* hash exclam exists on the first line the script will be executed using Busybox included in the distribution

If run as a command is selected the content should look like this:

.. code-block::

 sh -c "echo Test ${string_prompt:Parameter 1} ${string_prompt:Parameter 2}"

or if run as a script is selected a script with hash exclam must be specified:

.. code-block::

 #!/bin/sh
 echo Test ${string_prompt:Parameter 1} ${string_prompt:Parameter 2}
 for i in `seq 5 -1 0` ; do
 	echo Starting in $i seconds
 	sleep 1
 done
 echo Test started

Parameters can be specified using Eclipse variables or DVT :ref:`Custom Dialogs` can be used for more complex dialogs.

As a result you will be asked to provide the "Parameter 1" e.g. "run"
and "Parameter 2" e.g. "script". The result of running the command will be:

"Test run script"

.. note:: 
  
  The parameters ``${VAR}`` are considered Eclipse variables that and will be resolved before running the command. To use shell variables in the command you must use the ``$VAR`` syntax.
  
  When running as a command, unresolved Eclipse variables will trigger an error and the run will be aborted. not be reported. When running as a script the unresolved Eclipse variables will remain untouched.

**Supported Launch Modes**

You may choose if a launch configuration can be launched in Run mode, Debug mode or both.

When both modes are supported, launching from a :ref:`Custom Shortcut and Button for a Run Configuration` will prompt for launch mode.

See :ref:`Debugger Integration` for more details on debugging your code in DVT.

**Quick Run**

You can launch again at any time from menu :menuselection:`Run --> Run History...`` or directly from the toolbar (simple click launches last):

.. figure:: ../../images/vhdldt-launch-from-toolbar.png
	:align: center




**Output**

The invocation output is dumped to the **Console View**.

.. figure:: ../../images/vhdldt-external-builder-output.png
	:align: center




**Click on hyperlinks** in the Console View to jump directly to the to source location.


.. _Run Configuration Session Type:

Run Configuration Session Type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



.. note::
  
   This feature is available only for Linux and MacOS

The options available under the command/script text box can be used to control the process session that will be used to run the command or script. The following session types are available:

**Same process session as DVT**

-  The process will be a direct child of DVT

-  The process must manage its subprocesses if termination signals are received, otherwise orphaned processes may appear

-  Job control is not available

-  *stdin, stdout, stderr* will be available in **"Console View"**, *tty* will not be available

**A new process session**

-  The process will be launched using a wrapper script that will create a new process session

-  The process may manage its subprocesses if termination signals are received, but **"Terminate all spawned processes..."** option can be used to kill all subprocesses when the parent process ends or is terminated

-  Job control is available

-  *stdin, stdout, stderr* will be available in **"Console View"**, *tty* will not be available

**An xterm process session (xterm must be available in the system)**

-  The process will be launched using *xterm* that will create a new process session

-  The process may manage its subprocesses if termination signals are received, but **"Terminate all spawned processes..."** option can be used to kill all subprocesses when the parent process ends or is terminated

-  Job control is available

-  *tty, stdin, stdout and stderr* will be available in *xterm*, the *stdout, stderr* can be redirected to **"Console View"** using **"Redirect xterm output..."** option

-  *xterm* window can remain on screen when the process ends or is terminated if **"Hold xterm window open..."** option is selected

.. figure:: ../../images/common/dvt-run_configurations-dialog_2.png
	:align: center

.. _Custom Shortcut and Button for a Run Configuration:

Custom Shortcut and Button for a Run Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



On the main toolbar click on :menuselection:`Run --> Run Configurations... --> Select a DVT Generic run configuration` and click on :guilabel:`Shortcuts Tab`. 

You can choose to add a button in the main toolbar or a shortcut (for example, :kbd:`ALT+SHIFT+1`).

.. warning::
  
   It is not recommended to remove the shortcuts from :menuselection:`Window --> Preferences --> General --> Keys` you should remove them from the **Shortcuts Tab**. 

Toolbar buttons must have an icon. You can specify the path to an icon or generate one by selecting the :guilabel:`Generate icon` option. Each icon can have a one character label and a background color.

.. figure:: ../../images/common/run_configurations_shortcuts_tab.png
	:align: center




You can specify the position of a button in the toolbar by modifying the *Position #*. Buttons are placed in the toolbar from left to right, ordered from 0 to N. If there are more buttons with the same number, they will be ordered alphabetically.

.. figure:: ../../images/common/dynamic_shorcuts_on_toolbar.png
	:align: center


.. note::
  
  You cannot create shortcuts for read-only run configuration files.



.. _Using environment variables in DVT Generic Run Configurations:

Using environment variables in DVT Generic Run Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Environment variables can be set in the following ways:

-  in the shell where DVT was launched
-  using the **+dvt_setenv+** directive in the project's build configuration file (.dvt/default.build) - see :ref:`Environment Variables`
-  from the **Environment tab** of the **Run Configurations** dialog (menu :menuselection:`Run --> Run Configurations`)
-  directly within the command getting executed, for example: *sh -c "env PROJECT_DIR=${project_loc} iev -f ${project_loc}/iev/iev.f -c"*.

To ensure that an environment variable ``ENV_VAR`` is expanded correctly, use the simple ``$ENV_VAR`` notation.

Use the enclosing curly brackets ``${ENV_VAR}`` notation only for Eclipse specific variables. You can find a list of these
:ref:`DVT Generic Run Configuration Variables`.



.. _Using an alias in a DVT Generic Run Configuration:

Using an alias in a DVT Generic Run Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Aliases only work in interactive shells. The command specified in the Run Configuration should be:

.. code-block::

 <your_shell> -ic "<your_alias>"

for example

.. code-block::

 bash -ic "ll"

When you create a new DVT Generic Run Configuration, DVT tries to guess the shell that you use from the $SHELL system variable and fills it in for you.


.. _DVT Generic Run Configuration Variables:

DVT Generic Run Configuration Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



The following variables are available when you configure a run configuration. These variables are automatically expanded each time the run configuration is launched.



DVT variables

.. list-table::
   :header-rows: 1
   :widths: auto

   * - Name
     - Description
   * - ``${selected_resources_loc}``
     - Absolute file system path of the selected resources separated by system file separator character. You can pass as argument a string to be used as separator.
   * - ``${selected_resources_path}``
     - Workspace relative path of the selected resources separated by system file separator character. You can pass as argument a string to be used as separator.
   * - ``${selected_resources_name}``
     - The name of the selected resources separated by system file separator character. You can pass as argument a string to be used as separator.
   * - ``${selected_resource_line}``
     - The line of the cursor from the selected resource.
   * - ``${dvt_current_build_file}``
     - Absolute path to the current DVT build file
   * - ``${dvt_cli}``
     - Expands to the full DVT CLI path, using as the workspace option the current workspace: $DVT_HOME/bin/dvt_cli.sh -workspace ${workspace_loc}
   * - ``${dvt_sim_compile_file_list}``
     - List of files compiled by DVT, in compilation dependency order, including library and compile syntax information (VHDL only). Each line in the variable expansion has the format: <library> <langauage_syntax> <file_full_path>. If a file path is provided as an argument to this variable, all the files required for the compilation of the provided file are listed (including itself). If in addition "comp_deps" is provided as first argument, the entities instantiated through components will also be considered a compilation dependency




Eclipse variables

.. list-table::
   :header-rows: 1
   :widths: auto

   * - Name
     - Description
   * - ``${workspace_loc}``
     - The absolute path on the system's hard drive to Eclipse's workspace directory
   * - ``${workspace_loc:<resource path>}``
     - The absolute path on the system's hard drive to the specified resource. The <resource path> is the full path of the resource relative to the workspace root. For example ${workspace_loc:/MyProject/MyFile.txt}. Note that the expanded result of this variable is not the same as ${workspace_loc}/MyProject/MyFile.txt if the project's contents directory for MyProject is outside the workspace directory.
   * - ``${project_loc}``
     - The absolute path on the system's hard drive to the currently selected resource's project or to the project being built if the external tool is run as part of a build.
   * - ``${project_loc:<resource path>}``
     - The absolute path on the system's hard drive to the specified resource's project. The <resource path> is the full path of the resource relative to the workspace root. For example ${workspace_loc:/MyProject/MyFile.txt}. Note that the expanded result of this variable is not the same as ${workspace_loc}/MyProject if the project's contents directory for MyProject is outside the workspace directory.
   * - ``${container_loc}``
     - The absolute path on the system's hard drive to the currently selected resource's parent (either a folder or project).
   * - ``${container_loc:<resource path>}``
     - The absolute path on the system's hard drive to the specified resource's parent (either a folder or project). The <resource path> is the full path of the resource relative to the workspace root. For example:${workspace_loc:/MyProject/MyFolder/MyFile.txt}. Note that the expanded result of this variable is not the same as ${workspace_loc}/MyProject/MyFolder if the project's contents directory for MyProject is outside the workspace directory.
   * - ``${resource_loc}``
     - The absolute path on the system's hard drive to the currently selected resource.
   * - ``${resource_loc:<resource path>}``
     - The absolute path on the system's hard drive to the specified resource. The <resource path> is the full path of the resource relative to the workspace root. For example ${workspace_loc:/MyProject/MyFile.txt}. Note that the expanded result of this variable is not the same as ${workspace_loc}/MyProject/MyFile.txt if the project's contents directory for MyProject is outside the workspace directory.
   * - ``${project_path}``
     - The full path, relative to the workspace root, of the currently selected resource's project or of the project being built if the external tool is run as part of a build.
   * - ``${container_path}``
     - The full path, relative to the workspace root, of the currently selected resource's parent (either a folder or project).
   * - ``${resource_path}``
     - The full path, relative to the workspace root, of the currently selected resource.
   * - ``${project_name}``
     - The name of the currently selected resource's project or of the project being built if the external tool is run as part of a build.
   * - ``${container_name}``
     - The name of the currently selected resource's parent (either a folder or project).
   * - ``${resource_name}``
     - The name of the currently selected resource.


