Visual Studio Code extension

The Visual Studio Code editor

Microsoft® Visual Studio Code (VS Code) is a powerful source code editor available on various platforms.

Code completion, syntax highlighting, goto definition, code formatting, and debugging is possible for Genero .4gl and .per sources in VS Code after installing the VS Code extension for Genero BDL,

Installing VS Code

To start, you need to download and install Microsoft Visual Studio Code.

This documentation page does not explain how to use VS Code, you need to be familiar with this editor.

See https://code.visualstudio.com/ for more details.

Installing Genero BDL extension into VS Code

The Genero BDL extension can be installed in your VS Code environment by using the code --install-extension command with the .vsix file provided in the FGLDIR/lib directory. For example (note that the version number may be different with your installation):

$ code --install-extension $FGLDIR/lib/genero-fgl-0.0.18.vsix

Alternatively, you can start VS Code, go to the Extensions section, and load the Genero BDL .vsix extension file from FGLDIR/lib.

When upgrading the version of Genero BDL, re-install the VS Code extension file to get bug fixes and new features of this plugin.

When VS Code is started, you should see the Genero extension in the Extensions section.

Select the Genero extension and read the description.

Configuring global VS Code settings

Perform the following steps to setup VS Code for Genero BDL:

Start VS Code
Configure the editor to exclude .42? files:
- Open VS Code settings
- Select the "User" tab for global settings
- "Text Editor" → "Files: Exclude"
- Add **/*.42? to the pattern list
Configure the debugger to get inline values:
- Open VS Code settings
- Select the "User" tab for global settings
- Select "Features" → "Debug" → "Inline Values" → on

Create VS Code tasks for a project directory

Perform the following steps to setup VS Code for each of your Genero BDL projects:

Start VS Code
Open a folder with Genero BDL sources (there must be at least one .4gl source file in this directory in order to properly configure VS Code for Genero BDL). VS Code will consider this folder as the root dir for your project. Configuring VS Code tasks will automatically create a .vscode directory with configuration files.
Define a build task for Genero programs for this folder:
- Select "Terminal" → "Configure Default Build Task..."
- "Create task.json file from template" → "Others"
- Define the build task with attribute "problemMatcher": "$fglcomp". The "command" attribute must defined the build command, like "fglcomp -r --make -M *.4gl" to build all .4gl sources, or "make" to use a makefile. For example:
```
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "fglcomp-all-4gl",
      "type": "shell",
      "command": "fglcomp -r --make -M *.4gl",
      "problemMatcher": "$fglcomp",
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "group": {
        "kind": "build",
      }
    }
  ]
}
```
  See Genero extension description for details.
To compile .4gl sources, select "Terminal" → "Run Build Task..."
To compile .per form files, no need to add a build task in the task.json file:
- Select a .per form file in the file explorer
- Select "Terminal" → "Run Task..."
- Select "per: build all per files".

Define launch tasks for Genero programs:

Click on "Run and Debug" arrow on the left.
Click the "create a launch.json file" link
Select "Debug with fgldb-dap"
With launch.json file opened, click on the "Add Configuration..." button
Select "GeneroFgl Debug: Attach"

The launch task entries in launch.json should then look like this:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "fgldb-dap",
            "request": "attach",
            "name": "(4gl) Attach",
            "processId": "${command:pickProcess}"
        },
        {
            "type": "fgldb-dap",
            "request": "launch",
            "name": "(4gl) Launch",
            "program": "${workspaceFolder}/${fileBasenameNoExtension}",
            "args": ["interact"],
            "externalConsole": false,
            "cwd": "${workspaceFolder}"
        }
    ]
}

Configure VS Code for remote work

VS Code supports the Remote-Tunnels extension and the Remote-SSH extension to code, build and debug source Genero application code on a remote machine.

If the server where Genero development environment and application sources reside does not have an SSH server, or when no SSH client is available on your workstation, it is possible to install the VS Code Remote-Tunnels extension and the VS Code command-line interface (CLI) component on the server, to either connect from a workstation where a VS Code instance executes, or from a web browser without the need to install VS Code on the workstation. For more details, see VS Code documentation: Developing with Remote Tunnels.

When SSH server is available on the server and an SSH client is installed on the workstation, it is possible to use the Remote-SSH extension. Here are the steps to setup Remote-SSH for Genero FGL on a remote machine:

Prerequisite: You need an OpenSSH client on the workstation, that is compatible to Remote-SSH. See below the Remote-SSH link for more details.
Install VS Code on your workstation.
Install the Remote-SSH extension : Select "View" → "Extensions", search "Remote-SSH" in the marketplace and install it.
On the remote machine:
- Make sure that the SSH server and TCP port are reachable.
- Check that a Genero development environment is available and licensed.
- Write a shell script to setup the Genero environment and development environment. Source this shell script in the environment file of the user shell, like ~/.bashrc.
Follow the instructions in Remote-SSH extension help, to setup a remote ssh connection to the host where the source code resides:
- Select "View" → "Command Palette..."
- In the Command Palette prompt, type "Remote-SSH: Connect to host..."
- Enter the ssh command to connect to the remote host and setup the Genero environment and development environment of your source code. For example:
```
ssh myuser@myhost -A
```
- Enter remote user password when asked.
- A new VS Code session should open.
Install the Genero extension for the remote connection: Select "View" → "Extensions", clik on the ... three-dots → "Install from VSIX...", then browse the remote computer and select the Genero-FGL extension from FGLDIR/lib.
Select "File" → "Open Folder...": This should let you browse the disk on the remote machine.
Use local VS Code session as if the environment was local (see previous section for build tasks and debugger setup)

Debugging Genero programs with VS Code

After the Genero extension is installed in VS Code, open a folder that contains the source code of a Genero program, build and start a debug session as follows:

Select "Run" → "Start Debugging": The program starts in debug mode, and debugger stops at the first instruction of the program.
Go to the "DEBUG CONSOLE" tab: The prompt at the bottom allows you to evaluate expressions (for example, type sqlca + enter)
Go to the source code, and add a break point in one of the next lines.
Continue the program with F5, the program continues until the break point.
Right-click on the break point, and edit the break point (to add for example a condition)

VS Code can also attach to a running fglrun instance:

Go to the terminal tab or go to another terminal emulator, and start a program with GUI interface, using the same Genero environment.
In VScode, select the "Run and Debug" option, choose "(4gl) Attach", start debugging (F5), then choose a running fglrun process.
The progam should stop at the current instruction, and you can debug the source code.

Several debug sessions are possible. For example, when a program starts a child program with RUN, another debug session will start.