QNX launch configuration properties

Note:

You can find information about the Eclipse launch configuration templates in the Tasks > Running and debugging projects > Creating or editing a run/debug configuration entry of the C/C++ Development User Guide.

Also, the properties for Neutrino Kernel Event Trace are completely different than those of other QNX launch configuration types. The QNX File Transfer configuration type shows only the Common tab and its own File Transfer tab.

Main tab

Identifies the project, binary, build policy, and launch target. This tab is displayed by all launch configuration types designed for running, debugging, or analyzing an application.

Project

The project that this configuration applies to. You can enter the project name in the text field or click Browse to select the project from the workspace.

C/C++ Application

This field tells the IDE which binary file to run. You can name a file by specifying an absolute path on your host or a relative path within the project.

For some configuration types, there's an Auto-pick checkbox, which indicates whether the IDE should automatically select the binary file. By default, this box is checked. Automatic selection is convenient but it takes longer because the IDE must look for the binary file.

If you fill in the C/C++ Application text field and leave the box checked, the IDE treats the text field value as a hint. For example, suppose you have a project with two binaries—alpha and beta—and you compile the project for the x86_64 and AArch64le architectures. If the text field says build/x86_64-debug/alpha but you launch the project on an AArch64 target, the IDE auto-picks build/aarch64le-debug/alpha (and not build/aarch64le-debug/beta).

Note:

If you leave the text field blank, the IDE always auto-selects the binary file, even if Auto-pick is unchecked. Checking this box makes a difference only when you've named a binary file.

You can also specify an IDE variable as the text field value, by clicking the Variables button and selecting from the resulting list. Also, the Search Project button lets you pick from the list of binary files found within the project, while the Browse button brings up a file selector so you can pick a file from the local filesystem.

Build Configuration

The build configuration to use. This selection determines which binary version gets built (if required) before the project is launched. Note that this setting is significant only when Auto-build (explained below) is enabled.

The Build Configuration dropdown lists the build configurations for specific architectures and use cases (e.g., x86_64-coverage, aarch64le-debug), assuming your project uses standard makefiles. If it uses recursive makefiles, you'll see the Configuration option, which means the QNX C/C++ Project properties determine which binary versions get built.

For all projects, there's also the Use Active option, which tells the IDE to build the binary for the active build configuration, and the Select Automatically option, which makes the IDE select the build configuration based on the launch mode.

Auto-build

This set of radio buttons lets you choose an auto-building policy. The options are: Enable, Disable, or Use workspace settings.

When auto-building is enabled, if necessary, the IDE builds the appropriate binary file before running it on the target. When auto-building is disabled, if the IDE doesn't find the right binary file, an error message is displayed if you try to launch the project. The third option is handy if you want to use the same auto-build policy for all launch configurations.

Target

The target for running an application when you launch it using one of these two methods:

from the launch configuration manager, by clicking Run (or the equivalent task button) in the bottom right corner
from the Project Explorer, by right-clicking a project and selecting Run As, Debug As, or Profile As, then the launch configuration type from the submenu listings or the configurations selector, and then the launch configuration itself from the popup list

This property also tells the IDE which target connection to use to populate the file navigators for other properties, such as the remote directory for running the binary file. You can enter the target name into the text field or click Browse to select from the list of launch targets.

Arguments tab

Lists the command-line arguments, working directory, and some properties of the binary that gets run. All launch configuration types that start a process display this tab, for all launch modes except Attach.

C/C++ Program Arguments: The command-line arguments to pass to the executable binary. You don't need to include the executable file's name and you must separate the arguments with spaces (not commas or other characters). For example, if you want to send the equivalent command line of HelloWorld -v -L 2, type -v -L 2 into this text field.; The ${string_prompt} value instructs the IDE to prompt you for an argument every time you launch the application. You can have multiple entries like this, to display a prompt window for each input argument. Also, you can provide each prompt with its own label, by specifying values in the form of ${string_prompt:prompt_text}, where prompt_text is a text string without quotes and possibly containing spaces.
Working Directory: The target directory in which the executable runs. Initially, this box is unchecked, which means the executable runs in the same directory that it's uploaded to. This upload directory is defined by the Remote directory field in the Upload tab. If you uncheck the box, you can enter a different directory path in the text field or select a directory from a file selector.
Adaptive Partition: When you check this box, you can select the adaptive partition in which to run the executable. For an explanation of the concept and benefits of adaptive partitioning, see the Adaptive Partitioning chapter of the System Architecture guide for the OS version that your target is based on.
Priority and Scheduling: Checking this box lets you set the priority and scheduling algorithm for the threads of the application process. Information on thread priority and scheduling is found in the Thread Scheduling section of the System Architecture guide.
Test Runner: Checking this box lets you select a test framework to run unit tests. For information about the supported test frameworks and running test programs, see the Unit Testing chapter.

Environment tab

Defines environment variables for the target. This tab is displayed by all launch configuration types that support starting a process, for all launch modes except Attach. No variables are set by default, but you can add variable definitions with the following buttons:

New — Opens a prompt to enter a variable name and value. For the value, you can select an IDE variable (e.g., string_prompt).
Select — Opens a window that lists the environment variable settings of the host, allowing you to add any subset of those variable settings to the launch configuration.
Import — Opens a file selector that lets you choose a local file to read to populate the list of environment variable settings. The selected file must be a text file, with one name-value pair per line, in this format: VARNAME=value

There are also buttons on the side to edit or remove existing variable definitions, and radio buttons at the bottom to choose whether the environment variable settings shown here should be appended to or override the settings on the target.

Upload tab

Controls how the executable binary and other files are uploaded from the host to the target. All launch configuration types that involve starting a process display this tab, for all launch modes except Attach.

Upload executable to target

This option tells the IDE to upload the executable binary to the target (if necessary) when launching the project. When this radio button is selected (as by default), the text field is called Remote directory and it stores the location that the binary is uploaded to. You can either enter an absolute path or click Browse and select a directory from the file navigator. This directory must contain any shared libraries needed by the application, or you must upload those libraries by using the Upload shared libraries setting.

There are two checkboxes that also appear when this radio button is selected:

Strip debug information before uploading — When checked, the IDE removes debug information from the binary file before uploading it. This makes the file smaller and faster to upload, but means that you need a copy of it on the host to debug your program.
Use unique name — When checked, the IDE appends a number to the binary's filename to make it unique each time it's executed.

Use executable on target

This option tells the IDE to run an executable binary found on the target. When this radio button is selected, the text field is called Remote executable and stores the location of the executable. You can either enter an absolute path or click Browse and select a directory from the file navigator. This directory must contain any shared libraries needed by the application, or you must upload those libraries by using the Upload shared libraries setting.

Upload shared libraries or other files to the target before launch

When this box is checked (as by default), the IDE uploads the listed files to the target when launching the project. These files can be libraries, executables, or data files.

The Auto button populates the list with all libraries missing on the target. A library is missing if it's stored in a user (not system) path and listed in the NEEDED section of the executable binary. The Add button opens a window that provides a pre-populated list of workspace files but also lets you choose a file from the workspace or local filesystem.

Each entry shows the file's name, its host and target paths, and these two checkboxes:

Upload — indicates whether this file is included in the set of files uploaded
Strip — indicates whether to remove debug information before uploading the file

If you uncheck the Upload shared libraries box, the list is greyed out and no files are uploaded. However, the entries aren't deleted, meaning you can later reenable the uploading.

Remove uploaded components after session

Makes the IDE remove, from the target machine, the executable binary and any other uploaded files after the application finishes executing.

Debug tab

Enables or disables debugging and defines debugger options. The IDE uses the GNU Debugger, GDB. All launch configuration types that support debugging display this tab.

Debugger: This checkbox turns debugging on or off. When it's checked, you can see and set the debugger options. When the box is unchecked, the IDE hides the debugger options and doesn't attach the debugger when you launch the application.
Stop on startup at: When this option is set, the debugger stops when it enters the function named in the text field (by default, main()). The text field must be filled in when the box is checked.
GDB debugger: The GDB version to use. The default value of gdb means the IDE selects the version based on the architecture of the executable. The IDE comes with several GDB versions, each of which is named according to its supported architecture (e.g., ntoaarch64-gdb). Information on the debugger is given in the gdb entry in the Utilities Reference.; The only time you might want to change this field is if you're running a different gdb binary (e.g., a patched version) or if the IDE fails to pick the correct debugger version.
GDB command file: Provides the path of a file containing commands to be executed by GDB. The default path is .gdbinit.
Load shared libraries automatically: When this option is set, the debugger loads shared libraries used by the application and found on the host, so you can step through their code. You can uncheck this box to save memory on the host, because library symbols can consume significant memory.

Source tab

Defines the locations in which the debugger should look for source files. This tab is displayed by launch configuration types that support debugging.

Note:

You need to configure these settings only when debugging code not compiled on the host. For host-compiled code, the debugger can find the source files without hints from the user.

Source Lookup Paths

Lists the source containers, which define the paths for finding source code when debugging. The search order of the paths is from top to bottom in the list.

Initially, the list shows only one item, entitled Default, that groups three containers. You can't modify its contents but you can remove it and define your own containers.

If you click the Add button, the Add Source window appears and lists these container types:

Absolute File Path: Use any source file path compiled into the binary. The IDE interprets all paths as is, meaning if you're debugging a source file compiled with a path of /foo on another machine, your host machine must store that file at the same absolute path for the IDE to find it when debugging.
Compilation Directory: A local directory used for running the C/C++ compiler. You can specify the directory in the popup selector, which lets you browse the filesystem.
File System Directory: A local directory. This container type is similar to Compilation Directory except you can name any local directory, not just one used by the C/C++ compiler.
Path Mapping: A mapping of paths compiled into the binary to equivalent local paths. For instance, if the compilation path for some source files is /foo but the host location of these same files is /tmp/foo, you must define a mapping between these directories to allow the debugger to find the files on the host.
Program Relative File Path: Use any relative path compiled into the binary. You should use this container type when your host's directory structure matches that of the development system.
Project: One of more workspace projects. You can select these projects from a file selector. For each container of this type, the IDE searches recursively within the project, without considering the relative paths of the source files.
Project - Path Relative to Source Folders: This container type is similar to Project except that the IDE examines the relative paths in the compiled-in source file locations.
Workspace: All projects in the workspace.
Workspace Folder: One or more workspace folders. You can select these folders from a file selector.

If you need to revert to the original lookup paths, you can click the Restore Default button. There are also buttons for editing the location in directory-specific containers, deleting containers, and moving them up or down in the list to change the directory search order.

Search for duplicate source files on the path

When checked, the IDE continues to search the lookup paths for a source file with the same name even after finding the first file with a matching name.

Common tab

Specifies how the launch configuration is stored, displayed in toolbar menus, and other properties such as the standard input and output to use. All launch configuration types display this tab, but for QNX File Transfer configurations, only the Save As and Display in favorites menu fields are visible.

Save as

When you create a launch configuration, the IDE saves it as a .launch file. You can save this file in one of two locations:

Local file — The IDE stores the configuration file in workspace_dir/.metadata/.plugins/org.eclipse.debug.core/.launches.
Shared file — The IDE stores the configuration file in the workspace. You must either name a workspace path in the text field or choose a location from the folder selector.

Display in favorites menu

Adds the configuration to the favorites lists in the toolbar menus shown on the right of the launch bar. For example, if you check the boxes for Debug and Profile, you'll see the launch configuration in the favorites list in each of the Debug and Profile toolbar menus.

Encoding

The encoding scheme to use for console output. There are radio buttons to select either the default encoding scheme of UTF-8 or another scheme from the adjacent dropdown.

Allocate console (necessary for input)

When checked, the IDE assigns a console view to receive the input.

Input File

Names a file to redirect the standard input from. In the text field, you can enter an absolute path from the local filesystem or a relative path within the workspace. The buttons below let you select a file using a file selector, or use an IDE variable to define an input file.

Output File

Names a file to redirect the standard output to. In the text field, you can enter an absolute path from the local filesystem or a relative path within the workspace. The buttons below let you select a file using a file selector, or use an IDE variable to define the output file.

Append

When this box is checked, the IDE appends (and doesn't overwrite) the output file.

Launch in background

When this property is set (as is the default), the IDE carries out the launch configuration task in the background.

Libraries tab

Defines the paths in which the IDE tools can look to find shared libraries on the host. This tab is displayed by launch configuration types that support runtime analysis tasks, including debugging.

Shared Libraries Path: Lists the paths for finding shared libraries. The list entries can name files or directories, in the workspace or local filesystem. The search order of the paths is from top to bottom.; When you fill in the Project field in the Main tab, the IDE adds a list entry entitled System Paths. This entry contains the paths of any library files in the standard C or C++ library that are used by the project. You can't remove this entry but you can define your own entries. Also, you can uncheck any entry to exclude a file from the search paths.; The list also contains the Uploading Paths entry, which is auto-populated with the paths of any shared libraries named in the Upload tab.; The Auto button populates the list with all of the user libraries found on the host and listed in the NEEDED section of the executable binary. To add a directory to the list, click Add Path. This button brings up a window that lets you enter a folder path or pick a folder using a file selector.; To add a library file to the list, click Add Library. This button brings up a similar window, except that you're restricted to selecting a file.; There are also buttons for editing the path named in an entry, removing entries, and moving them up or down in the list, to change the search order of the library paths.
Validate and auto-populate library paths automatically prior to launching: When this box is checked (as by default), the IDE verifies that the library paths are up-to-date and if necessary, redefines those paths before each launch. You can uncheck this box after your target setup is done and you know that the library paths won't change anymore.

Tools tab

This last tab allows you to configure runtime analysis tools, and is shown by the C/C++ QNX Application and C/C++ QNX Attach to Remote Process launch configuration types. For the Debug, Run, and Attach modes, which support multiple tools, the tab is simply called Tools. For the modes dedicated to specific analysis tasks—Memory, Check, Profile, and Coverage—the tab name matches the mode.

The following radio buttons let you enable and configure the tools available for the current launch mode and launch configuration type (tools that are unavailable have their buttons disabled):

No Tool—lets you choose to not use a runtime analysis tool
Valgrind—enables controls for selecting a Valgrind tool and configuring general and tool-specific options
Application Profiler—lets you set the profiling method, scope, and function profiling options
Memory Analysis—lets you specify the types of memory errors to check for, stack tracing parameters, when to take memory snapshots, and other settings
Code Coverage—lets you specify the source files to analyze for code coverage, the polling interval, and more

There's also a checkbox for enabling the System Profiler, which can run concurrently with other tools. Explanations of how to configure and use these tools are given in the Integrated tools section.