DVT IDE for VS Code VHDL User Guide
Rev. 24.1.5, 13 March 2024

26.1.1 dvt_code.sh Syntax

Usage: dvt_code.sh [ createProject | connect | version | help ] ...

  Start VS Code / VSCodium
    -code_args       <args>  Additional VS Code / VSCodium arguments.
    -reuse_window            VS Code / VSCodium will reuse the last active window.
    -noexit                  Script will not terminate after VS Code / VSCodium is started.

  Start VS Code / VSCodium and create a language server:
    createProject <project path> -lang <lang> [-name <name>]
                  [-build <name>] [-f|-F <file>] [-<name>.build <....>]
                  [-map <name> <path>] [-files_exclude <glob>]
                  [-use_available] [-local] [-port_range <start> <end>]
                  [-heap_size <size>] [-stack_size <size>] [-vmargs <args>]
                  [-code_args <args>] [-reuse_window]
                  [-noexit]

    Mandatory arguments:
      <project path>         Path to project (must exist).
      -lang   <lang>         Project language (vlog, vhdl).

    Optional arguments:
      -name          <name>      Friendly name for this language server.
      -build         <name>      Name of active build configuration.
      -f|-F          <file>      Specify a command file for the project. -f and -F are mutually exclusive.
      -<name>.build  <....>      Create the build configuration file <project>/.dvt/<name>.build with <....> 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, or -F.
      -map    <name> <path>      Specify additional folders to be opened alongside the project folder in VSCode / VSCodium Explorer View.
      -files_exclude <glob>      Exclude from VS Code / VSCodium Explorer View the files and folders matched by the pattern.
                                 The pattern matches the relative from root path of a resources,
                                 where the root is the project folder or any of the mapped folders.
                                 Glob syntax:
                                   *   match zero or more characters in a path segment.
                                   ?   match on one character in a path segment.
                                   **  match any number of path segments, including none.
                                   {}  group conditions ({**/*.log,**/*.out} matches all .log and .out files).
                                   []  match a range of characters ([0-9] matches on 0, 1, 2, ...).
                                   [!] match any character except the range of characters ([!0-9] matches a, b, ... but not 0, 1, 2, ...).
      -use_available             Connect to an available language server with the same project path and build name.
      -local                     Language server will bind to the '127.0.0.1' address, only connections from the same machine will be accepted.
      -heap_size     <size>      Set the Java heap size (syntax is <N>[g|G|m|M|k|K]). Default is 3072m.
      -stack_size    <size>      Set the Java thread stack size (syntax is <N>[g|G|m|M|k|K]). Default is 4m.
      -port_range <start> <end>  Choose ports in range [<start>, <end>] for communication with language server.
      -vmargs        <args>      Additional Java arguments.
      -code_args     <args>      Additional VS Code / VSCodium arguments.
      -reuse_window              VS Code / VSCodium will reuse the last active window.
      -noexit                    Script will not terminate after VS Code / VSCodium is started.

  Start VS Code / VSCodium and connect to a language server:
    connect <id> | <port@host> | <name>
           [-code_args <args>] [-reuse_window] [-noexit]

    Mandatory arguments (exactly one):
      <id>                   Language server's id
      <port@host>            Language server's port and host
      <name>                 Language server's name

    Optional arguments:
      -code_args     <args>  Additional VS Code / VSCodium arguments.
      -reuse_window          VS Code / VSCodium will reuse the last active window.
      -noexit                Script will not terminate after VS Code / VSCodium is started.

  Show language server version:
    version

  Environment variables:
    DVT_CODE_BIN            Path to VS Code / VSCodium executable binary.
                            Default is $DVT_HOME/codium/bin/codium when running from a DVT distro.
                            This variable must be set when manually installing the extension from VSIX or from Extension Marketplace
                            and the script is part of the extension installation directory.

Using the script without providing the createProject or connect commands starts a VS Code / VSCodium and restores its last known state.

createProject

Starts VS Code / VSCodium with and automatically creates a project as follows:

1. A Language Server is started with the arguments provided after the createProject command, these arguments are forwarded to dvt_ls.sh as they are and if they are missing they will be inferred or defaults will be used as described in dvt_ls.sh documentation. When use_available argument is provided, the script will look for an available (reachable and unused) Language Servers matching the same project path, build name and language and if any server is found it will be used in the second step.

2. VS Code / VSCodium is started with the folder <project path> loaded, then it connects to the Language Server started or identified in the first step.

connect

Starts VS Code / VSCodium and connects to a running Language Server specified by <id>, <port@host> or <name>, the folder on which that Language Server was started will be loaded into the VS Code / VSCodium automatically.

Notes about other arguments:

  • The <project_path>, build <name>, lang <lang>, name <name>, heap_size <size>, stack_size <size> are passed as they are to the dvt_ls.sh start ... command.

  • Arguments can be passed to the VS Code / VSCodium process using code_args argument.

  • By default the script starts VS Code / VSCodium in background and ends, returning the control of the terminal. In some situations (e.g. when dispatching the job into a computer farm) it is preferable to run the script as a foreground job in which case noexit flag must be used.