Customizing launch configurations

QNX Toolkit1.1QNX Toolkit User's GuideDeveloperSetup

You can customize the launch configuration by editing the launch.json file or creating multiple launch configurations.

The following default template configurations are included:

  • C/C++ QNX: Attach (attaches the debugger to an existing process identified in the launch configuration)
  • C/C++ QNX: Launch (uploads and runs the program at a specific path on the target)
  • C/C++ QNX: Run Tracelogger (runs the tracelogger utility on a target system)

You can create your own configurations when you need to customize how a project runs, and then reuse those custom settings. For more information about launch configurations, go to the Debugging page in the VS Code documentation.

Editing the launch configuration

Use the Add Configuration button to view or edit your launch configurations, or add template configurations for common tasks.

You can edit the launch.json file to customize the launch configuration, or create multiple launch configurations. Follow the steps below:

  1. From the workspace of the project, click the launch.json file.
  2. Use the Add Configuration... button to add launch configurations using templates.
  3. Edit the fields based on your requirements.

Available launch options in the configuration

The qnx-gdb launch configuration takes an executable in your workspace (auto-detected using the qnx.autodetectBinary command), uploads it to the target, and executes it with various environment variables set in the base directory script (refer to the env entry in the table below).

Attributes for the qnx-gdb launch configuration

Attribute Description
gdb The absolute path to the host GNU debugger (e.g., ntox86_64-gdb). Default is per target architecture nto|gdb. Default: gdb.
program The path to the program to launch on the host. If the program only exists on the target, set path to "-" (hyphen) and use the remotePath option to set the path. Default: ${command:qnx.autodetectBinary}.
remotePath The path on the target to upload the program to. Default is uploadLocation/programBaseName.
args The arguments for the program.
env The environment variables for the program. You can use any environment variable via env. prefix. If you have variable XXX, you can use ${env.XXX} in launch configuration to access its value. Default: empty list
cwd The path to the current working directory of the target process. Default: uploadLocation.
priority The main thread priority when launched (2-253).
policy The scheduling policy (see system documentation for details)
qnxtarget The name of the target to launch the program on (configured via Target Navigator) or host:port. If set to prompt, it asks to select the target dynamically. If set to default, it launches on the default target. Default: default.
stopAtEntry If set to true, the debugger stops at the entry-point of the target (ignored on attach). Default: false.
initCommands The additional gdb commands to use when starting.
verbose Produce verbose log output. Default: false.
logFile The absolute location of the log file.
upload Upload the binary. Default: true.
uploadLocation The folder on the remote host where temp files are uploaded by default, including the main binary. Default: /tmp.
additionalSOLibSearchPath The additional directories where the debugger can find symbols (e.g., additionalSOLibSearchPath: /path/to/symbol/files). These directories are automatically added to solib-search-path for gdb.
autoUploadSOLib Automatically uploads required shared libraries using additionalSOLibSearchPath to search. Default: true.
files The additional files to upload or download (depending on the value of the operation attribute) to the target before launching the program. Refer to the specifications of the files attribute below.
Specifications for the files attribute
Setting Type Description Default
hostPath string The path to upload the file to on the host -
remotePath string The path to upload the file to on the target -
remotePermissions string The permissions for the file on the target in octal format 660
operation 
enum: [
         "upload", 
         "download", 
         "download-stream"
       ]
 The kind of file operation expected:
  • Upload the file to the target before the process launches
  • Download the file after the process terminates"
  • Download the file while running the process (stream)"
 upload

Example 1: basic launch

This basic launch takes an executable qnx binary at hard-coded path /nto/x86_64/o/myprogram in your workspace, uploads it to the target, and executes it. 

{
      "type": "qnx-gdb",
      "request": "launch",
      "name": "nto/x86_64/o/myprogram",
      "gdb": "gdb",
      "program": "${workspaceFolder}/nto/x86_64/o/myprogram",
      "qnxtarget": "default",
      "upload": true
},

Example 2: launch with arguments

The launch with arguments is similar to the basic launch, but also defines the args and env variables. 

{
    "type": "qnx-gdb",
    "request": "launch",
    "name": "nto/x86_64/o/myprogram",
    "gdb": "gdb",
    "program": "${workspaceFolder}/nto/x86_64/o/myprogram",
    "qnxtarget": "default",
    "upload": true
    "args": ["1","2","3"],
    "env": {
       "LD_DEBUG": "1"
    }
},

Example 3: launching a script

This launch takes the script.py script in your workspace, uploads it to the target at the specificed remotePath, then executes it using the python binary, which already exists on the target. 

{
    "type": "qnx-gdb",
    "request": "launch",
    "name": "python",
    "gdb": "none",
    "program": "python",
    "upload": "false",
    "qnxtarget": "default",
    "preLaunchTask": "",
    "args": ["/tmp/script.py"],
    "files": [
      {
         "hostPath": "${env:HOME}/script.py",
         "remotePath": "/tmp/script.py"
      }
   ]
},

Available attach options in the configuration

The qnx-gdb attach configuration attaches the debugger to an existing process with name myprogram (since processId is not specified in launch.json). In addition, it sets the search path for debugging shared libraries.

Attributes for the qnx-gdb attach configuration

Attribute Description
gdb The path to gdb.
program The path to the program to be debugged. Default: ${workspaceFolder}/${command:AskForProgramPath}.
remotePath The path to the binary on the remote target (or the name of the process).
processId The ID of the process to attach to. Leave empty to search by the program name.
qnxtarget The name of the target to launch the program on (configured via Target Navigator) or host:port. If set to prompt, it asks to select the target dynamically. If set to default, it launches on the default target. Default: default.
verbose Produce a verbose log output. Default: false.
logFile The absolute location of the log file.
additionalSOLibSearchPath The additional directories where the debugger can find symbols (e.g., additionalSOLibSearchPath: /path/to/symbol/files). These directories are automatically added to the solib-search-path for gdb.
initCommands The additional gdb commands used during the startup.

Example 4: basic attach

In this example, the qnx-gdb attach configuration attaches to an existing qnx binary at /nto/x86_64/o/myprogram in your workspace and debugs it. It also sets the search path additionalSOLibSearchPath to a shared library. 
{
    "type": "qnx-gdb",
    "request": "attach",
    "name": "qnx attach myprogram",
    "gdb": "gdb",
    "program": "${workspaceFolder}/nto/x86_64/o/myprogram",
    "processId": "",
    "verbose": true,
    "logFile": "/tmp/attach.log",
    "additionalSOLibSearchPath": "${workspaceFolder}/build/x86_64-debug",
    "qnxtarget": "default"
},

Additional variables resolved in launch configurations

You can add the following variables in the options field in the launch.json file:

Variable Description
${command:qnx.autodetectBinary}Attempts to find a matching binary that's best for this launch, including the target architecture and name of the binary (using the remotePath option and the name of the configuration).
${self:target.arch}Target architecture of the current launch target (may not be the default value if you used the qnxtarget setting). This value matches the name of the top level directory of $QNX_TARGET (i.e., aarch64le).
  • ${self:target.cpu} Target CPU without endian and variant (i.e., aarch64, arm, or x86_64).
  • ${self:target.endian} Target endian; either be or le
  • ${self:target.endian_variant} Empty for x86_64; use -le for other platforms. Directory paths use this value.
  • ${self:target.variant} Use -v7 for armle-v7; empty for all other architectures.
For example, if you want to use variables for a default binary path for recursive make (i.e., ${workspaceFolder}/nto/aarch64/o-le/myprogram), then use ${workspaceFolder}/nto/${self:target.cpu}/o${self:target.endian_variant}/${workspaceFolderBasename}.
${self:xxx}Refers to the configuration itself, so xxx is any scalar variable defined in the launch configuration (use a relative path to access subobjects).
${env:QNX_TARGET}The path to QNX_TARGET. VS Code sets this variable based on the SDP path you selected (qnx.sdpPath), so this variable may not be same as the actual environment variable.
${command:qnx.debug.askProgramPath}Prompts the user to enter the filepath.
${command:qnx.debug.askTargetAddress}Prompts the user to enter the IP address or host name.
${command:qnx.debug.askForTarget}Prompts the user to select the QNX target.
${command:qnx.debug.askProcessId}Prompts the user to select the process ID.
${command:qnx.askForString}Prompts the user to select any strings.
${command:qnx.targets.getDefaultTargetHost}Returns the host IP address of the default QNX target.

Additional variables resolved in VS Code

VS Code supports variable substitution in launch.json and .vscode/task.json files by using the ${variableName} syntax. You can use any variable that VS Code resolves. Refer to the Variables reference page in the VS Code documentation for the list of predefined variables.

Page updated: