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, diagnostics 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.

Setup Genero environment

Before installing the VS Code extension for Genero, and before starting VS Code once Genero extension is installed, it is mandatory to setup the Genero BDL environment in order to access Genero tools like fglcomp and fglform.

For example, on a Microsoft Windows OS, if you start VS Code from the start menu, and Genero BDL environment is not implicitly set for the user or system, the VS Code extension will not work.

For more details about Genero environment setup, see Installing Genero BDL.

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.

The next example uses a .vsix file with the version number 19. The Genero BDL version installed on your system may provide an extension file with a more recent version number:

$ code --install-extension $FGLDIR/lib/genero-fgl-0.0.19.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:
  1. Start VS Code
  2. 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
  3. Configure the editor to avoid suggestion selection on Enter:
    • Open VS Code settings
    • Select the "User" tab for global settings
    • "Text Editor" → "Suggestions" → "Accept suggestion on Enter"
    • Set the option to off.
  4. Configure the debugger to get inline values:
    • Open VS Code settings
    • Select the "User" tab for global settings
    • Select "Features" → "Debug" → "Inline Values"
    • Set the option to on.

Create VS Code tasks for a project directory

Perform the following steps to setup VS Code for each of your Genero BDL projects:
  1. Start VS Code
  2. 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.
  3. Define a build task for Genero programs for this folder:
    • Select "Terminal" → "Configure Default Build Task..."
    • "Create tasks.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.
  4. To compile .4gl sources, select "Terminal" → "Run Build Task..."
  5. To compile .per form files, no need to add a build task in the tasks.json file:
    • Select a .per form file in the file explorer
    • Select "Terminal" → "Run Task..."
    • Select "per: build all per files".
  6. 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": [],
            "stopAtEntry": true,
            "externalConsole": false,
            "cwd": "${workspaceFolder}"
        }
    ]
}
      Notes:
      1. Adapt the stopAtEntry parameter to stop for debug at the first executable line in the MAIN block (true), or stop for debug at the first breakpoint (false).
      2. Adapt the externalConsole: When set to false, vscode runs the program to debug in it's current shell. When true, the program gets run in a new shell and will pick up the full shell environment (for example, on Linux: .bash_profile and .bashrc) - this is mandatory if your Genero and additional tools (like JDK) environment settings are defined in the user shell scripts.
      3. Command-line arguments can be passed to the program with the "args" field. Each argument needs to be specified as an individual string in a JSON array:
        "args": ["-g", "--username", "tom", "--port", "2134"]
      4. Environment variables can be defined for the "launch" request, by adding an "env" object, with a set of properties in the form "var-name":"value" pairs. Use null as value, to unset an existing environment variable:
        "env":{ "TMPDIR" : "/tmp", "TMP" : null }
        Note:

        Use the launch configuration option env, only if this launch target requires individual environment variables. General environment variables can be set for the terminal (enter settings, enter ‘terminal env’ in the search bar). A typical use case is FGLSERVER. If the scope of the setting is User then this value of FGLSERVER is used in any terminal of a VSCode remote connection.

Configure VS Code for remote work

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

If the host with Genero development environment and application sources 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:
  1. Prerequisite: You need an OpenSSH client on the workstation, that is compatible to Remote-SSH. See below the Remote-SSH link for more details.
  2. Install VS Code on your workstation.
  3. Install the Remote-SSH extension : Select "View" → "Extensions", search "Remote-SSH" in the marketplace and install it.
  4. On the remote development host:
    • 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. Define FGLSERVER to use the TCP port that is port-forwarded by the SSH connection in VS Code. Source this shell script in the environment file of the user shell, like ~/.bashrc.
  5. 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 development environment. If you want to display application forms on a local front-end of the workstation in a secure way, use remote port forwarding with the -R option of the ssh command. For example:
      ssh mike@devhost -R 127.0.0.1:6400:127.0.0.1:6400
      with TCP port forwarding, fglrun processes started by VS Code on the remote server will display to the front end listening on a local workstation TCP port.
    • Enter remote user password when asked.
    • A new VS Code session should open.
  6. 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.
  7. Select "File" → "Open Folder...": This should let you browse the disk on the remote machine.
  8. Make sure you have the parameter externalConsole set to true in the launch.json file.
  9. 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:
  1. Select "Run" → "Start Debugging": The program starts in debug mode, and debugger stops at the first instruction of the program.
  2. Go to the "DEBUG CONSOLE" tab: The prompt at the bottom allows you to evaluate expressions (for example, type sqlca + enter)
  3. Go to the source code, and add a break point in one of the next lines.
  4. Continue the program with F5, the program continues until the break point.
  5. 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:
  1. Go to the terminal tab or go to another terminal emulator, and start a program with GUI interface, using the same Genero environment.
  2. In VScode, select the "Run and Debug" option, choose "(4gl) Attach", start debugging (F5), then choose a running fglrun process.
  3. 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.