.. _DVT Auto-Linked:

DVT Auto-Linked
===============

.. rst-class:: lead

   
Some of the files that DVT compiles for a project may be located outside the project directory (see :ref:`What is a Project`). In order to benefit from DVTs advanced functionalities on such files, they are automatically linked as if inside the project, under the **<project_root>/DVT Auto-Linked** virtual folder. A virtual folder is a logical container - it has no physical representation on the disk.

For example, a file physically located in:


 /path/to/my/base/classes/file.ext

will be Auto-Linked under the following virtual folder hierarchy:

.. code-block:: bash

  ./<project_root>
  ├── DVT Auto-Linked/
  │   ├── path/
  │       └── to/
  │           └── my/
  │               └── base/
  │                   └── classes/
  │                       └── file.ext/
  └── ...

You can create new files or open existing ones anywhere in the DVT Auto-Linked hierarchy.

For creating new files, you can use the New File Wizard. The files thus created will have a representation on the disk.

For opening existing files, you can right click on any folder in the DVT Auto-Linked hierarchy and select Open from the context menu. A File Chooser will appear that will help you find the file that you want.

In the case of very deep hierarchies, you can define "aliases" for paths using the ``+dvt_auto_link_root+<alias>=<root_path>`` directive. These aliases are called DVT Auto-Linked Roots.

For example by adding this line in the project's default.build:

.. code-block::

  +dvt_auto_link_root+base_classes=/path/to/my/base/classes/

the following virtual folder hierarchy is created:

.. code-block:: bash

  ./<project_root>
  ├── DVT Auto-Linked/
  │   ├── base_classes/
  │       └── file.ext/
  └── ...


The specified <root_paths> and <aliases> must be unique, and therefore only the first occurrence is considered.

Aliases may not be names of directories located directly under the filesystem root (like for example **/etc** or **/bin**).

Environment variables may be used when specifying root paths, for example:

.. code-block::

 +dvt_auto_link_root+src=$HOME/a/b/c

.. note::

  - An environment variable may only be used at the beginning of a root path (that is, the following will not work: **+dvt_auto_link_root+src=/path/$VAR/a/b/c**)
  - Only environment variables inherited from the console where DVT was started may be used. Variables defined using **+dvt_setenv+** are not allowed.
  - The **+dvt_auto_link_root+** directive may only be used in the first invocation

.. rubric:: More examples

.. code-block::

  +dvt_auto_link_root+hdl=/a/b/c

.. code-block::
  :caption: All auto-linked files with a path that starts with /a/b/c will be presented in DVT Auto Linked/hdl

  +dvt_auto_link_root+hdl=/a/b/c
  +dvt_auto_link_root+hdl/d/e/f

.. code-block::
  :caption: The second directive will be ignored because the same "hdl" alias was used.

  +dvt_auto_link_root+hdl=/a/b/c
  +dvt_auto_link_root+src=/a/b/c

.. code-block::
  :caption: The second directive will be ignored because the same "/a/b/c" path was used.

  +dvt_auto_link_root+hdl=/a/b
  +dvt_auto_link_root+src=/a/b/c

All files under /a/b/c will be presented under src and the rest from /a/b under hdl.

