.. _Commands:

Commands
========


.. _Create a Project (Mixed-Language Capable):

Create a Project (Mixed-Language Capable)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

    createProject <project_path> [-workingset [-newwindow]] [-force] [-close_others]
            [-f|-F <file_path>] [-top <top_file_path>] [-test <test_file_path>]
            [-map <link_name> <target_path>] [-name <project_name>]
            [-lang <lang>] [-perspective <perspective>] [-clearcase]
            [-git <repo1:repo2:...:repoN>] [-p4 <connection_parameters>]
            [-openResourceFilterDialog]
            [-include auto[:<threshold>]] [-include first_level] [-disable_fs_check]
            [-exclude|include :ref:`name`][,root=folder1[:sub/folderN]][,applies=f|d|rf|rd]]
            [-build <name>] [-<name>.build <build configuration directives ...>]

Mandatory arguments:

.. code-block:: console

    <project_path> Absolute path to project (must exist).
    -lang          Enable support for <lang> language: E, VLOG, VHDL, CPP, CPP_EXT, PSS, SLN, SDL, PF. 
                   CPP, CPP_EXT are only valid when DVT CDT Integration feature is installed.
                   At least one language must be specified.

Optional arguments:

.. code-block:: console

    -<name>.build     Create the build configuration file <project>/.dvt/<name>.build with
                      <build configuration directives> as content. All flags up to the end of the
                      command line, or up to the next -<name>.build flag are considered build
                      configuration directives. This flag cannot be used in conjunction with
                      -f, -F, -test, or -top.

    -build <name>     Set <name> as active build configuration.

    -clearcase        Share project with ClearCase Eclipse plugin.

    -include auto[:<threshold>]
                      Automatically create resource filters, based on the active build configuration.
                      Only compilation related directories are included, for example +incdirs, -y libdirs, 
                      $SPECMAN_PATH entries and parent directories of top files.
                      If specified, directories with more than <threshold> files will be excluded; otherwise, 
                      all relevant directories containing compiled files will be included.
                      Some configuration resources are always included: .buildpath, .classpath, .cproject, .dvt, 
                      .project, .pydevproject, .settings
                      
                      
          [NOTE]      The -include auto argument can be combined with any further user-specified include or exclude filters

    -include first_level
                      Automatically create resource filters to include only the files and directories (without their content) 
                      located directly under the project root.
                      The directories' content can be brought on demand, level by level, by double clicking on a directory
                      in the Project Explorer View.
                      Some configuration resources are always included: .dvt, .settings
                      For more details see the Lazy Bring-up Resources chapter.

    -disable_fs_check By default, a filesystem check is performed to determine if the project directory sits on top of 
                      a large filesystem tree (more than 50000 children) or if the project directory is located on a slow filesystem 
                      (listing all the files takes more than 10 seconds). 
                      In such a situation, there is a high risk of running into refresh performance problems. To avoid this, 
                      the -include auto and -include first_level options are added automatically to the command.
                      Use this flag to disable the filesystem check and the automatic injection of -include auto and -include first_level.

    -exclude|include  [name|location|projectRelativePath[_regex]=<pattern>,][root=folder1[:sub/folderN],][applies=f|d|rf|rd]
                      or
                      [symlink=[true|false],][root=folder1[:sub/folderN],][applies=f|d|rf|rd]

                      Create resource filters.
                      Use include to keep files or directories matching <pattern>.
                      Use exclude to filter out files or directories matching <pattern>.

                      Syntax details:

                      [name|location|projectRelativePath[_regex]=]<pattern>
                        If only <pattern> is specified it is equivalent with name=<pattern>.
                        For <name|location|projectRelativePath>=<pattern>, the pattern is case insensitive and allows simple wildcards (* and ?).
                        For <name_regex|location_regex|projectRelativePath_regex>=<pattern>, the pattern is case sensitive and allows regular expressions.
                        
                      symlink=true|false
                        When symlink=true only symlinked resources are matched by the filter.
                        When symlink=false only non-symlinked resources are matched by the filter.

                      root=folder1[:sub/folderN]
                        By default filter applies to project root children, unless you specify one or more roots.

                      applies=f|d|fr|dr
                        By default filter applies recursively to files and directories under root(s), unless you restrict it:
                          f = filter applies only to _f_iles under root(s)
                          d = filter applies only to _d_irectories under root(s)
                          rf = filter applies _r_ecursively to _f_iles under root(s)
                          rd = filter applies _r_ecursively to _d_irectories under root(s)
                      
                      For example, given this project hierarchy: 
                      
                      | cli_resource_filters_example
                      |-- .dvt
                      | |-- default.build
                      |-- folder_1
                      | |-- folder_1_1
                      | | |-- folder_1_1.log
                      | | |-- some_file.sv  
                      | |-- folder_1_2
                      | | |-- folder_1_2.log
                      | | |-- some_file.sv
                      | |-- folder_1.log
                      | |-- some_file.sv
                      |-- folder_2
                      | |-- folder_2_1
                      | | |-- folder_2_1.log
                      | | |-- some_file.sv  
                      | |-- folder_2_2
                      | | |-- folder_2_2.log
                      | | |-- some_file.sv
                      | |-- folder_2.log
                      | |-- some_file.sv
                      |-- .project
                      |-- dvt_build.log
                      
                      * to exclude a sub-directory of the project, including all of its content:
                      
                      dvt_cli.sh -workspace ~/dvt_workspace createProject ~/projects/cli_resource_filters_example/ -lang VLOG -exclude projectRelativePath=folder_2,applies=d
                      
                      | cli_resource_filters_example
                      |-- .dvt
                      | |-- default.build
                      |-- folder_1
                      | |-- folder_1_1
                      | | |-- folder_1_1.log
                      | | |-- some_file.sv  
                      | |-- folder_1_2
                      | | |-- folder_1_2.log
                      | | |-- some_file.sv
                      | |-- folder_1.log
                      | |-- some_file.sv
                      |-- .project
                      |-- dvt_build.log
 
                      * to include only particular sub-directories of the project:
                      
                      dvt_cli.sh -workspace ~/dvt_workspace createProject ~/projects/cli_resource_filters_example/ -lang VLOG -include projectRelativePath=folder_1 -include projectRelativePath=folder_1/folder_1_1 
                      -include projectRelativePath=folder_1/folder_1_1/*
                      
                      | cli_resource_filters_example
                      |-- .dvt
                      | |-- default.build
                      |-- folder_1
                      | |-- folder_1_1
                      | | |-- folder_1_1.log
                      | | |-- some_file.sv
                      |-- .project
  
                      * to exclude all the files which have their names matching a regular expression:
                      
                      dvt_cli.sh -workspace ~/dvt_workspace createProject ~/projects/cli_resource_filters_example/ -lang VLOG -exclude name_regex=.*.log,applies=rf
                      
                      | cli_resource_filters_example
                      |-- .dvt
                      | |-- default.build
                      |-- folder_1
                      | |-- folder_1_1
                      | | |-- some_file.sv  
                      | |-- folder_1_2
                      | | |-- some_file.sv
                      | |-- some_file.sv
                      |-- folder_2
                      | |-- folder_2_1
                      | | |-- some_file.sv  
                      | |-- folder_2_2
                      | | |-- some_file.sv
                      | |-- some_file.sv
                      |-- .project
                      
                      The root parameter instructs the filter application to a relative point in the project hierarchy.
                      * Suppose the case of removing some log files, but only starting with a certain point in the project hierarchy:
                      
                      dvt_cli.sh -workspace ~/dvt_workspace createProject ~/projects/cli_resource_filters_example/ -lang VLOG -exclude name_regex=.*.log,root=folder_2,applies=rf
                     
                      | cli_resource_filters_example
                      |-- .dvt
                      | |-- default.build
                      |-- folder_1
                      | |-- folder_1_1
                      | | |-- folder_1_1.log
                      | | |-- some_file.sv  
                      | |-- folder_1_2
                      | | |-- folder_1_2.log
                      | | |-- some_file.sv
                      | |-- folder_1.log
                      | |-- some_file.sv
                      |-- folder_2
                      | |-- folder_2_1
                      | | |-- some_file.sv  
                      | |-- folder_2_2
                      | | |-- some_file.sv
                      | |-- some_file.sv
                      |-- .project
                      |-- dvt_build.log
                    	
                      * If the case, you can also specify multiple roots for a filter (for example exclude all the log files in folder_1/folder_1_2 and folder_2):
                      
                      dvt_cli.sh -workspace ~/dvt_workspace createProject ~/projects/cli_resource_filters_example/ -lang VLOG -exclude name_regex=.*.log,root=folder_1/folder_1_2:folder_2,applies=rf
                      
                      | cli_resource_filters_example
                      |-- .dvt
                      | |-- default.build
                      |-- folder_1
                      | |-- folder_1_1
                      | | |-- folder_1_1.log
                      | | |-- some_file.sv  
                      | |-- folder_1_2
                      | | |-- some_file.sv
                      | |-- folder_1.log
                      | |-- some_file.sv
                      |-- folder_2
                      | |-- folder_2_1
                      | | |-- some_file.sv  
                      | |-- folder_2_2
                      | | |-- some_file.sv
                      | |-- some_file.sv
                      |-- .project
                      |-- dvt_build.log
                    	
                    	 
          [NOTE]      Resource filters are also applied for linked resources (such as those created by -map)
          [NOTE]      You can specify any number of include or exclude filters. 
          [NOTE]      Regardless the specified order, all the include filters will be applied before the exclude filters.
          [NOTE]      Do not use trailing slashes when specifying a directory pattern.
          [NOTE]      DVT provides a user interface for managing Resource Filters as a simpler and more
                      intuitive alternative to the Eclipse built-in Resource Filters management UI.
                      However, DVT's UI only works for <projectRelativePath> filters that do not
                      contain wildcards or regular expressions.

    -f|-F             Specify a command file for the project. -f and -F are mutually exclusive.

    -force            Overwrite existing project.

    -git              Add the specified repositories to the Git Repositories View. A colon (:) separated
                      list of repository paths must be provided.
          [NOTE]      Repository paths must include (end with) the /.git segment.

    -map              Create a linked resource called <link_name> pointing to <link_target>.

    -name             Use as project name instead of project's directory name.

    -newwindow        Open a new window with the working set selected.
    
    -openResourceFilterDialog
                      Open the project's DVT Resource Filters dialog.

    -p4               Share project with Perforce Eclipse plugin. The <connection_parameters>
                      argument must be specified as a list of <parameter>=<value> separated by commas.
                                Mandatory parameters:
                                    P4PORT=<host:port> (P4PORT=company_server:1666)
                                    P4CLIENT=<perforce_workspace_name> (P4CLIENT=perforce-work)
                                    P4USER=<username> (P4USER user1)
                                Optional parameters:
                                    P4CHARSET=<charset_type> (P4CHARSET=none)
                                    P4PASSWD=<password> (P4PASSWD=password123)
                                    SAVEPASS=<save_in_secure_storage_or_not> (SAVEPASS=false)
                                    OFFLINE=<working_offline_or_not> (OFFLINE=false)

    -perspective      Switch to <perspective> after creating the project.
                      By default, DVT switches to the DVT Perspective if multiple -lang directives are provided.
                      If a single language is enabled, the corresponding perspective is activated.
                      Valid argument values: DVT, E, VLOG, VHDL, CPP, PSS, SLN, SDL, or a perspective ID.
                      Perspective IDs provided by the additional plugins included in the DVT distro:
                        JDT - org.eclipse.jdt.ui.JavaPerspective
                        LUA - org.eclipse.ldt.ui.luaperspective
                        PERL - org.epic.core.Perspective
                        PYTHON - org.python.pydev.ui.PythonPerspective
                        RUBY - org.eclipse.dltk.ruby.ui.RubyPerspective
                        TCL - org.eclipse.dltk.tcl.ui.TclPerspective
                        CVS - org.eclipse.team.cvs.ui.cvsPerspective
                        GIT - org.eclipse.egit.ui.GitRepositoryExploring
                        SVN - org.eclipse.team.svn.ui.repository.RepositoryPerspective
                        PERFORCE - com.perforce.team.ui.perforcePerspective
                        COLLABORATOR - com.smartbear.collaborator.ui.collabPerspective

    -svn              Share project with the Subversive SVN Eclipse plugin.
                      The SVN repository URL must be provided.
                      The repository is added to the SVN Repositories View if not existing.

    -test             Specify a test file for the project. You can specify this option multiple times.

    -top              Specify a top file for the project. You can specify this option multiple times.

    -workingset       Add project to a working set.
    
    -close_others     Close all projects in the workspace except the newly created one.

.. seealso::

    :ref:`Lazy Bring up Resources`
    
    :ref:`How to create resource filters`

Create a Project From an Existing Template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. code-block:: console
 
 createProjectFromTemplate <target_path> -template <template_path>

Creates a project into the workspace from an existing :ref:`project template<Project Templates>`.

.. code-block:: 

     <target_path>       absolute path to target directory
     <template_path>     absoulute path of the project template

Import an Existing Project
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

 importProject <project_path> [-workingset [-newwindow]] [-force] [-close_others] 
               [-clearcase] [-git <repo1:repo2:...:repoN>][-p4 <connection_parameters>]

Mandatory arguments:

.. code-block:: console

    <project_path> absolute path to project

Optional arguments:

.. code-block:: console

    -force          Use this flag to overwrite an existing project with the same name but a different location.

    -clearcase      Share project with ClearCase Eclipse plugin.
    
    -git            Add the specified repositories to the Git Repositories View. A colon (:) separated
                    list of repository paths must be provided.
       [NOTE]       Repository paths must include (end with) the /.git segment.
    
    -newwindow      Open a new window with the working set selected.
    
    -p4             Share project with Perforce Eclipse plugin. The <connection_parameters>
                    argument must be specified as a list of <parameter>=<value> separated by commas.
                            Mandatory parameters:
                                P4PORT=<host:port> (P4PORT=company_server:1666)
                                P4CLIENT=<perforce_workspace_name> (P4CLIENT=perforce-work)
                                P4USER=<username> (P4USER user1)
                            Optional parameters:
                                P4CHARSET=<charset_type> (P4CHARSET=none)
                                P4PASSWD=<password> (P4PASSWD=password123)
                                SAVEPASS=<save_in_secure_storage_or_not> (SAVEPASS=false)
                                OFFLINE=<working_offline_or_not> (OFFLINE=false)

    -svn            Share project with the Subversive SVN Eclipse plugin.
                    The SVN repository URL must be provided.
                    The repository is added to the SVN Repositories View if not existing.

    -workingset     Add project to a working set.
    
    -close_others   Close all projects in the workspace except the newly imported one.
    

List Compiled Files
~~~~~~~~~~~~~~~~~~~

.. code-block:: 

 listCompiledFiles -project <project_name>[ -unique][ -dirs][ -separator <separator>][ -lang <lang>]

List all the files compiled in the specified project, in compilation order.

.. code-block:: console
    
    -project    The project for which you want the list of compiled files.
    -unique     [Optional] Remove duplicates form the list.
    -dirs       [Optional] Get a list of parent directories of the compiled
                           files instead of the files themselves.
    -separator  [Optional] Specify a custom separator for the list elements;
                           default is newline.
    -lang       [Optional] List only the files compiled in <lang> language(s).
                           You may specify this argument multiple times to select multiple languages.
                           Valid argument values: E, VLOG, VHDL.
                           If not specified, all compiled files are listed, regardless of language.
                           
Compare Files
~~~~~~~~~~~~~

.. code-block:: console

 compareFiles [ <baseFile> ] <leftFile> <rightFile> [ -base <baseFile> ] [ -blocking ]
 
Compares two or three files.

.. code-block:: console
    
    -base       [Optional] Specify the base file for a three-way comparison.
    -blocking   [Optional] Block the console until the Eclipse Compare Editor is closed


Launch a Run Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

 launchRunConfig [-blocking] [-debug] -name <run_config_name>

Launch a Run Configuration
    
.. code-block:: console
    
    -blocking   [Optional] return after the Run Configuration has completed
    -debug      [Optional] launch the Run Configuration in debug mode
    -name       Name of the Run Configuration to launch

Open a File
~~~~~~~~~~~

.. code-block:: 

 openFile <path_to_file>[ -line <line_number>][ -project <project_name>][ -showInNavigator ]

Open the file denoted by <path_to_file> in the DVT editor.
    
.. code-block:: console
    
    -line            [Optional] select and reveal the specified line in the editor;
                     lines are counted from 1
    -project         [Optional] try to open the file from the specified project
                     If the file does not exist in the given project, it is opened
                     from any other project in the workspace.
                     If the file does not exist in any project, it is opened
                     out of any context (limited DVT capabilities).
    -showInNavigator 
        [Optional] reveal the specified file in the Eclipse Navigator View

Close a File
~~~~~~~~~~~~

.. code-block:: console

 closeFile <path_to_file>[ -forceSave]

Close the file denoted by <path_to_file> in the DVT editor.
    
.. code-block:: console
    
    -forceSave  [Optional] save the file before closing the editor.
                If the file contains any unsaved changes and this option
                is not used, a save dialog will appear in DVT.


Open a Custom Dialog
~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

 openCustomDialog -file <path_to_swtxml> [-project <project_name>] [-nonblocking]

Open a custom dialog and return the values that were filled in.
    
.. code-block:: console
    
    -file         .swtxml file describing the custom dialog. Either an
                  absolute path or a path relative to project root
    -project      [Optional] specify a project for the Custom Dialog
    -nonblocking  [Optional] dialog will not block the UI while opened (non-modal)

Open a Perspective
~~~~~~~~~~~~~~~~~~

.. code-block:: console

 openPerspective <perspective_name>

Open the specified perspective.
The perspective name may contain whitespace characters (for example "e Language").
Note: Preserves the UI focus across the perspective change.

Refresh a Project
~~~~~~~~~~~~~~~~~

.. code-block:: console

 refreshProject <project_name> [-subpath <subpath>] [-depth <depth>]

Refresh a project or a <subpath> in a project.

.. code-block:: console

    -subpath    [Optional] Only refresh <project_path>/<subpath>. May be a
                folder or a file.
    -depth      [Optional] Only refresh to the provided depth. By default the
                refresh depth is 2, that is full (recursive) refresh.
                Possible values for <depth> are:
                    2 the resource and its direct and indirect members at any depth
                    1 the resource and its direct members
                    0 the resource, but not any of its members
                    
Rebuild a Project
~~~~~~~~~~~~~~~~~

.. code-block:: console

 rebuildProject <project_name> [-build <name>]
 
Rebuilds the specified project.

.. code-block:: console

    -build <name>     [Optional] Set <name> as active build configuration.

Rebuild All Projects
~~~~~~~~~~~~~~~~~~~~

.. code-block:: console  

 rebuildAllProjects
 
Rebuilds all the projects in the workspace.

Print Edited File
~~~~~~~~~~~~~~~~~

.. code-block:: console

 printActiveEditorFile [-name_only] [-strip_extension]

Prints the full path of the file opened in the active editor.
    
.. code-block:: console
    
    -name_only        [Optional] Print only the filename.
    -strip_extension  [Optional] Strip the file extension, if any.

Quit
~~~~

.. code-block:: console

 quit

Quit DVT


Query the running status
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

 status

Query the running status of DVT.


Print version
~~~~~~~~~~~~~

.. code-block:: console

 version

Print the DVT version number.


Run Performance Exploration
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

 runXpl -project <project_name> -features <feature1:feature2:...:featureN> [-part <part>] [-filters <filter1:filter2:...:filter3>] [-generate_automatic_waivers -runtime <runtimeValue> -occurrences <occurencesValue>]

Run Performance Exploration

.. code-block:: console 
    
    -project                    The project on which you want to run the Performance Exploration.
    -features                   The features you want to run the Exploration with (can be one of
                                these three: hyperlink, incremental, content_assist).
    -part                       [Optional] By default the Performance Exploration will run on the
                                whole project(default value: FULL), but can be set to one of these
                                values: 1/5, 2/5, 3/5, 4/5, 5/5 meaning that it will run on the N-th
                                fifth of the whole project.
    -filters                    [Optional] Filters you want to apply on the files from the selected project.
    -generate_automatic_waivers 
        [Optional] This option enables creation of automatically generated waivers,
        'runtime' and 'occurrences' options are mandatory when this tag exists
    -runtime                    [Optional] Set the minimum runtime(in milliseconds) of the
                                current scope's feature execution which will trigger the creation of a
                                generated performance waiver.
    -occurrences                [Optional] Set the minimum occurrences of the current scope
                                which will trigger the creation of a generated performance waiver.
    -skip_recompiled_files      [Optional] By default, files compiled multiple times are analyzed on each occurrence.
                                This option enables skipping on said files.
