The launch configuration properties are defined in multiple tabs and fields that vary with the launch configuration type.
For those types that support QNX projects, you can configure C/C++ project properties, runtime analysis tools, and settings
for uploading binaries to a target.
Note:
You can find information about the Eclipse launch configuration templates in the
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—called alpha
and beta—and you compile the project for the x86 and ARMv7 architectures.
If the text field says build/x86-debug/alpha but you launch
the project on an ARMv7 target, the IDE auto-picks build/armv7-debug/alpha
(and not build/armv7-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-coverage, armv7le-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 resulting submenu,
and finally, the launch configuration 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.
The Adaptive Partitioning chapter of the System Architecture guide explains the concept and benefits of
adaptive partitioning.
- 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., ntoarmv7-gdb).
Information on the debugger is given in the gdb entry in the QNX Neutrino 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.