Difference between revisions of "VMS IDE how to"

From VSI OpenVMS Wiki
Jump to: navigation, search
Line 251: Line 251:
  
 
====To download files from a remote machine to the local====
 
====To download files from a remote machine to the local====
# Set the value of downloadNewFiles option (see Updating project settings for details) in the vmssoftware.synchronizer-settings.json file
+
# Set the value of '''downloadNewFiles''' option (see Updating project settings for details) in the '''vmssoftware.synchronizer-settings.json''' file
# Invoke “Command Palette”: press <Ctrl>+<Shift>+<nowiki><P></nowiki>
+
# Invoke “'''Command Palette'''”: press <Ctrl>+<Shift>+<nowiki><P></nowiki>
# Type “>vms-ide: synchronize project files with VMS” in the Command Palette bar
+
# Type ''“>vms-ide: synchronize project files with VMS”'' in the '''Command Palette''' bar
# Select the “vms-ide synchronize project files with VMS” command from the drop-down list
+
# Select the ''“vms-ide synchronize project files with VMS”'' command from the drop-down list
  
  
 
[[Category:VMS IDE]]
 
[[Category:VMS IDE]]

Revision as of 08:48, 13 April 2021

Installing Visual Studio Code

To start working with VMS IDE you need to install Visual Studio Code editor.

  1. Go to https://code.visualstudio.com/
  2. Click the download dropdown button and select the build for your platform (Windows, Mac, or Linux). The installer will be downloaded.
  3. Run the installer and follow the instructions

(!) This guide uses Visual Studio Code for Windows

Installing VMS IDE extension

  1. Select Extensions view in the Activity Bar
  2. Type “vms ide” into the search box
  3. Select VMS IDE extension
  4. Click the Install button in the Extensions view
Install VMS IDE

VS Code will install the extension. To verify that it is installed:

  1. Go to FilePreferencesSettings
  2. Type “vms ide” to the Search bar in the Settings tab

The extension will be displayed in the list of settings:

verify vms ide is installed

Creating and setting up a project

Creating a project folder

To start working on your project you need to open the folder that will be used as a project folder.

  1. Select the Explorer view in the Activity bar
  2. Click the Open Folder button
  3. Select a folder for the project in the dialog window and click the Select Folder button.
open project 2

The selected folder is shown in the Explorer tab. All project files and directories will be shown in this panel.

project is open

The alternative way to open the folder: FileOpen folder… → Select a folder for the project

Updating workspace settings

From the official page of VS Code:
A Visual Studio Code "workspace" is the collection of one or more folders that are opened in a VS Code window (instance). In most cases, you will have a single folder opened as the workspace but, depending on your development workflow, you can include more than one folder, using an advanced configuration called Multi-root workspaces. Before you start working on your project you need to set up your workspace. Two important options that you need to set are

  • End of Line character
  • Type of configuration

End of Line Character

To select the end of line character:

  1. Click the Manage icon in the Activity bar
  2. Click Settings in the popup menu
  3. Select Workspace in the Settings tab
  4. Type “eol” in the search bar
  5. Select “\n” (LF) in the Files: EOL drop-down list
select eol

After changing EOL the .vscode directory with settings.json will be created in your project folder.

Type of configuration

To select the type of configuration:

  1. Select Extensions view in the Activity bar
  2. Right-click the Gear icon of the VMS IDE extension
  3. Click the Extension Settings
  4. Select the Using Type item of the config from the drop-down list. We recommend using FS (default value)
Type of configuration is setting

All project, ssh, and other settings will be saved in JSON files in the .vscode directory of the project folder.

Updating project settings

Create a project configuration file

You need to create a file with project configuration and specify your project settings in it:

  1. Click the View menu option
  2. Select Command Palette… option from the View menu
  3. Type “>VMS-IDE: edit VMS project settings” in the Command Palette bar
  4. Select the “VMS-IDE: edit VMS project settings” command from the drop-down list
edit project settings 1

The editor opens vmssoftware.synchronizer-settings.json

  1. Specify your project settings (see info about parameters and values below).
  2. Save file: press <Ctrl>+<S> or select File → Save

The vmssoftware.synchronizer-settings.json file will be saved in the .vscode directory in the root of the project folder.

Customize project configuration

After the file is created you need to customize it specifying the parameters. The structure of the vmssoftware.synchronizer-settings.json file consists of 3 sections:

  • Project - general project settings
  • Synchronize - synchronizer specific settings
  • Builds- build configurations for the project

(!) Follow the links to view all the options for each section.

Generally, in the project section you need to:

  1. Set the root directory. For example, if the project is located in WORK:[USER.DEMOS.SIMPLE] and the home directory is WORK:[USER], set the parameter value to demos/simple or /work/user/demos/simple
  2. Select the projectType that you need
  3. Specify the projectName. WARN: Do not use spaces or special characters in the projectName
  4. Check builders. These files will be synchronized.
  5. Check headers. These files will be synchronized and included in the auto-generated MMS file as header files. Changing any of them will result in a full project rebuild.
  6. Check source. These files will be synchronized and included in the auto-generated MMS file as source files.
  7. Check resource. These files will be synchronized but not included in the auto-generated MMS file.
  8. Adjust the exclude field value to list the files similar to the described above but not to be synchronized and compiled.
  9. Check listing. These files will be downloaded after building the project. Files "*.lis,*.map" are required for the debugger.
  10. If the project depends on already installed libraries, specify them in the addLibraries and addIncludes


Glob syntax:

* to match one or more characters in a path segment
? to match one character in a path segment
** to match any number of path segments, including none
{} to group conditions (for example {**/*.html,**/*.txt} matches all HTML and text files)
[] to declare a range of characters to match (example.[0-9] to match on example.0, example.1, …)

Generally, in the synchronize section you need to: Select the downloadNewFiles value - strategy for downloading remote files that are newer than local copies.

  • If you have the full project on OpenVMS and want to download it to your local machine, set downloadNewFiles to overwrite.
  • If you have the full project on your local machine and use OpenVMS only for compiling and debugging, set downloadNewFiles to skip.
  • If the project on OpenVMS can be changed outside and may be newer than the local copy, set downloadNewFiles to edit.


Generally, in the build section you need to:

  1. Specify label - unique name of the build configuration. Note: the label is also used as the name of the output folder.
  2. Add a description - description of the build configuration

By default, there are two build configurations:

  • DEBUG, which is necessary for debugging
  • RELEASE, which produces binaries for your project deployment.

For custom build configurations for your project see here. Example of vmssoftware.synchronizer-settings.json

{
    "project": {
        "break": "C",
        "builders": "*.{mms,com,opt}",
        "exclude": "**/{.vscode}/**,**/.git/**,*gitignore*",
        "headers": "*.h",
        "listing": "*.lis,*.map",
        "outdir": "out",
        "projectName": "NEW_PROJECT",
        "projectType": "executable",
        "resource": "**/resource/**",
        "root": "/USR_DISK/TEST_USER/NEW_PROJECT",
        "source": "*.{cpp,c,cld,msg}",
        "addCompQual": "",
        "addCompDef": "",
        "addLibraries": "",
        "addIncludes": ""
    },
    "synchronize": {
        "downloadNewFiles": "edit",
        "keepAlive": false,
        "preferZip": false,
        "forceLocalTime": true,
        "purge": false,
        "setTimeAttempts": 3
    },
    "builds": {
        "configurations": [
            {
                "label": "DEBUG",
                "description": "NEW_PROJECT 1.0.1 debug,
                "command": "",
                "parameter": "DEBUG"
            },
            {
                "label": "RELEASE",
                "description": "NEW_PROJECT 1.0.1 release",
                "command": "",
                "parameter": "RELEASE"
            }
        ]
    }
}

Updating SSH settings

Create SSH settings configuration file

For syncing source code files, building, running, and debugging project you need to create a file with SSH configuration and specify your SSH settings in it:

  1. Select the View menu option
  2. Select Command Palette… option from the View menu
  3. Type “>VMS-IDE: edit VMS ssh-helper settings” in the Command Palette bar
  4. Select the “VMS-IDE: edit VMS ssh-helper settings” command from the drop-down list
edit ssh settings 1

The editor opens vmssoftware.ssh-helper-settings.json

  1. Specify your SSH settings (see info about parameters and values below).
  2. Save file: press <Ctrl>+<S> or select File → Save

The vmssoftware.ssh-helper-settings.json file will be saved in the .vscode directory in the root of the project folder.

Customize SSH settings configuration file

After the file is created you need to specify the required parameters. The vmssoftware.ssh-helper-settings.json file consists of 4 sections:

  • connection - the current connection details
  • host-collection - a list of connections required for the project
  • timeouts - SSH connection timeouts
  • terminal - command to start the shell in the VS Code integrated terminal


Generally, in the connection section you need to specify:
Required

  1. Specify host - IP-address or name of an OpenVMS machine or the label of a predefined connection from the host collection section. In the latter case, all other fields in the connection section are ignored.
  2. username - User account that will be used for the SSH connection.

Optional

  1. password - User password that will be used for the SSH connection. If it is omitted, a password input box will be shown on a connection attempt.
  2. keyFile - Path to the SSH private key file. For details on how to configure a connection using an SSH key, see SSH public key authentication on OpenVMS

If you need to connect to different servers when working on your project specify their settings in the host collection section. Typically the settings for every host are:

  • label - label for the current host's settings. It can be used as a host in the connection section
  • host
  • password or key
  • port
  • username

To use one of the connections from the host collection section, copy the label value and paste it in angle brackets (<label>) to the host field in the connection section.

Example of vmssoftware.ssh-helper-settings.json for a project with 2 hosts.

 
{
    "connection": {
        "host": "<Boston keys>" 
    },
    "host-collection": {
        "hosts": [
            {
                "host": "104.207.199.181",
                "keyFile": "h:/.ssh/sv01",
                "port": 22,
                "username": "vorfolomeev",
                "label": "Boston keys" 
            },
            {
                "host": "104.207.199.181",
                "keyFile": "",
                "port": 22,
                "username": "vorfolomeev",
                "label": "Boston pass" 
            }
        ]
    },
    "timeouts": {
        "cmdTimeout": 0,
        "feedbackTimeout": 0,
        "welcomeTimeout": 0
     },
    "terminal": {
        "command": ""
    }
}

Follow the link to view all options for each section.

Working on a project

Synchronizing

Synchronizing allows you to transfer your project files between remote and local machines. Synchronization lists files on a VMS machine and your local machine starting from the root directory. The files are identified by the source, headers, builders, resource masks. Files matching masks listed in the exclude section are ignored.


To download files from a remote machine to the local

  1. Set the value of downloadNewFiles option (see Updating project settings for details) in the vmssoftware.synchronizer-settings.json file
  2. Invoke “Command Palette”: press <Ctrl>+<Shift>+<P>
  3. Type “>vms-ide: synchronize project files with VMS” in the Command Palette bar
  4. Select the “vms-ide synchronize project files with VMS” command from the drop-down list