Launch Configurations Reference

You can select a topic from this diagram:

Glossary What's New Utilities Used by the IDE Getting System Information Using Code Coverage Common Wizards Reference Preparing Your Target Developing Photon Applications Developing C/C++ Programs Where Files Are Stored Building OS and Flash Images Migrating to the 6.3 Release Tutorials IDE Concepts About This Guide Analyzing Your System With Kernel Tracing Profiling an Application Finding Memory Errors Debugging Programs Managing Source Code Launch Configurations Reference

Workflow diagram with launch configurations chapter highlighted


You must set up a Launch Configuration before you can run or debug a program.

In this chapter:

What is a launch configuration?

To run or debug programs with the IDE, you must set up a launch configuration to define which programs to launch, the command-line options to use, and what values to use for environment variables. The configurations also define which special tools to run with your program (e.g. the Code Coverage tool).

The IDE saves your launch configurations so you can quickly reproduce the particular execution conditions of a setup you've done before, no matter how complicated.

Each launch configuration specifies a single program running on a single target. If you want to run your program on a different target, you can copy and modify an existing launch configuration. And you can use the same configuration for both running and debugging your program, provided that your options are the same.

Types of launch configurations

The IDE supports these types of launch configurations:

C/C++ QNX QConn (IP)
If you're connecting to your target machine by IP, select this configuration (even if your host machine is also your target). You'll have full debugger control and can use the Application Profiler, Memory Trace, and Code Coverage tools. Your target must be running qconn.
C/C++ QNX PDebug (Serial)
If you can access your target only via a serial connection, select this configuration. Rather than use qconn, the IDE uses the serial capabilities of gdb and pdebug directly. This option is available only when you select Debug.
C/C++ Local
If you're developing on a self-hosted system, you may create a C/C++ Local launch configuration. You don't need to use qconn; the IDE launches your program through gdb.
C/C++ Postmortem debugger
If your program produced a dump file (via the dumper utility) when it faulted, you can examine the state of your program by loading it into the postmortem debugger. This option is available only when you select Debug. When you debug, you're prompted to select a dump file.
PhAB Application
If you wish to run a PhAB application, follow the steps for creating a C/C++ QNX QConn (IP) launch configuration.

The main difference between the C/C++ QNX QConn (IP) launch configurations and the other types is that the C/C++ QNX QConn (IP) type supports the runtime analysis tools (QNX System Profiler and QNX Memory Trace).

Running and debugging the first time

You can use the same launch configuration to run or debug a program. Your choices in the Launch Configurations dialog may cause subtle changes in the dialog but greatly affect such things as:

The Run and Debug menu items appear in the C/C++ Development perspective by default, but they may not appear in all perspectives. You'll need the Run-->Run... menu item in order to set up a launch configuration. To bring the menu item into your current perspective:

  1. From the main menu, select Window-->Customize Perspective.
  2. Select the Commands tab.

    Customize Perspective - Commands

  3. Check the Launch box in the Available command groups list.
  4. Click OK.

Debugging a program the first time

To create a launch configuration in order to debug a program for the first time:

  1. In the C/C++ Projects or Navigator view, select your project.
  2. From the main menu, select Run-->Debug... (or, click the Debug icon and select Debug... from the dropdown menu).
  3. Select a launch configuration type:

    Launch Configuration dialog

    If you're connecting to your target via IP, select C/C++ QNX QConn (IP). If not, see the "Types of launch configurations" section in this chapter before deciding.

  4. Click New. The dialog displays the appropriate tabs.
  5. Give this configuration a name.
  6. Fill in the details in the various tabs. See the "Setting execution options" section in this chapter for details about each tab.
  7. Click Debug. You can now launch and debug your program.

Note: You can also use the Debug As menu item to conveniently select a particular launch configuration:

Debug As item


Running a program the first time

When you configure a program to run, you should also configure it to debug as well.


Note: There are fewer options for running programs than for debugging. Some configurations aren't available.

To run a program the first time:
Repeat the procedure for debugging a program (see "Debugging a program the first time"), with the following changes:

Note:

You can also use the Run As menu item to conveniently select a particular launch configuration:

Debug As item


The IDE also lets you run a program without creating a launch configuration, but the program's output doesn't appear in the Console view.

To run a program without using the launcher:

  1. After building the program, drag the executable from the C/C++ Projects view to a target listed in the Target File System Navigator view. (To learn more about the view, see the "Moving files between the host and target" in the Building OS and Flash Images chapter.)
  2. In the Target File System Navigator view, right-click your file and select Run. When the dialog appears, click OK. Your program runs.

Running and debugging subsequent times

Once you've created a launch configuration, running or debugging a program is as easy as selecting that configuration. You can do this in several ways:

Launching a selected program

To debug or run a program that you've created a launch configuration for:

  1. From the main menu, select Run-->Debug... or Run-->Run....
  2. In the left pane, select the launch configuration you created when you first ran or debugged your program.
  3. Click Debug or Run.

Launching from a list of favorites

If you have a program that you launch frequently, you can add it to the Debug or Run dropdown menu so you can launch it quickly.


Note: To use this method, you must have selected Display in favorites when you first created your launch configuration. If you didn't, edit the Display in favorites menu option under the Common tab. See "Setting execution options" in this chapter.

To debug or run a program using your favorites list:

  1. Do one of the following:

    You'll see a list of all the launch configurations you specified in the Display in favorites menu:

    Launch Configuration dialog; running a program subsequent times (faster)

  2. Select your launch configuration.

Launching the last-launched program

To relaunch the last program you ran or debugged:
Press F11 or click the dropdown button (Icon: Menu dropdown) beside the Debug or Run icon, then select your launch configuration.

Setting execution options

The Launch Configurations dialog has several tabs:


Note: All of these tabs appear when you select the C/C++ QNX QConn (IP) type of launch configuration; only some tabs appear when you select the other types.

Main tab

This tab lets you specify the project and the executable that you want to run or debug. The IDE might fill in some of the fields for you:

Launch Configurations dialog; Main tab

Different fields appear in the Main tab, depending on the type of configuration you're creating. Here are descriptions of all the fields:

Project
Enter the name of the project that contains the executable you want to launch. You may also locate a project by clicking Browse.... You can create or edit launch configurations only for open projects.
C/C++ Application
Enter the relative path of the executable's project directory (e.g. x86/o/Test1_x86). For QNX projects, an executable with a suffix of _g indicates it was compiled for debugging. You may also locate an available executable by clicking Search Project....
Target Options
General Options
If you're creating a C/C++ QNX PDebug (Serial) launch configuration, then you'll see the Stop in main option, which is set on by default. This means that after you start the debugger, it stops in main() and waits for your input.

Note: For serial debugging, make sure that the pseudo-terminal communications manager (devc-pty) is running on your target.

Serial Port Options
Here you can specify the serial port (e.g. COM1 for Windows hosts; /dev/ser1 for Neutrino) and the baud rate, which you select from the dropdown list.

Arguments tab

This tab lets you specify the arguments your program uses and the directory where it runs.

Launch - Arguments tab

C/C++ Program Arguments
Enter the arguments that you want to pass on the command line. For example, if you want to send the equivalent of myProgram -v -L 7, type -v -L 7 in this field. You can put -v and -L 7 on separate lines because the IDE automatically strings the entire contents together.
Working directory on target
The option Use default working directory is set on by default. This means the executable runs in the /tmp directory on your target. If you turn off this option, you can click Browse... to locate a different directory.

Environment tab

The Environment tab lets you set the environment variables and values to use when the program launches. For example, if you want to set the environment variable named PHOTON to the value /dev/photon_2 when you run your program, use this tab. Click New to add an environment variable.

Launch - Environment tab

Download tab

The Download tab lets you tell the IDE whether to transfer an executable from the host machine to the target, or to select one that already resides on the target.

Launch - Download tab

Executable
If you select Download executable to target, the IDE sends a fresh copy of the executable every time you run or debug.

The Download directory on target field shows the default directory of /tmp on your target. If you select the Use executable on target option, you'll need to specify a directory here. You can also use the Browse... button to locate a directory.

The Strip debug information before downloading option is set on by default. Turn it off if you don't want the IDE to strip the executable you're downloading to your target.

The Use unique name option is set on by default. This means the IDE makes your executable's filename unique (e.g. by appending a number) during each download session.

Extra libraries
The Extra libraries pane lets you select the shared libraries your program needs. If you click the Auto button, the IDE tries to automatically find the libraries needed. If you click From project, the IDE looks in your workspace for libraries.

You also have the option of not downloading any shared libraries to your target.

By default, the IDE removes the files it has downloaded after each session. If you don't want the IDE to "clean up" after itself, then turn off the Remove downloaded components after session option.

Debugger tab

The Debugger tab lets you configure how your debugger works. The content in the Debugger Options pane changes, depending on the type of debugger you select:

Launch Configurations dialog; Debugger tab


Note: The settings in the Debugger tab affect your executable only when you debug it, not when you run it.

Generic debugger settings

Debugger
The debugger dropdown list includes the available debuggers for the selected launch-configuration type. The list also varies depending on whether you're debugging a remote or a local target.
Stop on startup at
This option is set on by default and the default location is main()(). If you turn it off, the program runs until you interrupt it manually, or until it hits a breakpoint.
Advanced button
Click the Advanced button to display the Advanced Options dialog:

Advanced debug options

Enable these options if you want the system to track every variable and register as you step through your program. Disable the option if you want to manually select individual variables to work with in the Variables view in the debugger (see the Debugging Your Programs chapter). Disabling the Registers option works the same way for the Registers view.


Note: If you choose to track all the variables or registers, your program's performance may suffer.

Debugger Options

GDB command file
This field lets you specify a file for running gdb using the -command option (see the Utilities Reference).
Load shared library symbols automatically
This option (on by default) lets you watch line-by-line stepping of library functions in the C/C++ editor. You may wish to turn this option off if your target doesn't have much memory; the library symbols take up RAM on the target.

You can use the pane to select specific libraries or use the Auto button to have the IDE attempt to select your libraries.

Stop on shared library events
Choose this option if you want the debugger to break automatically when a shared library or DLL is loaded or unloaded.

Source tab

The Source tab lets you specify where the debugger should look for source files. By default, the debugger uses the source from your project in your workspace, but you can specify source from other locations (e.g. from a central repository).

Launch - Source tab

To specify a new source location:

  1. On the Source tab, click Add.... The Add Source Location dialog appears. You may choose to add the source either from your workspace or elsewhere:
    1. If you wish to add source from your workspace, select Existing Project Into Workspace, click Next, select your project, and then click Finish.
    2. If you wish to add source from outside your workspace, select File System Directory, and then click Next.
  2. Type the path to your source in the Select location directory field or use the Browse button to locate your source.

    If you want to specify a mapping between directories, choose the Associate with option and enter the directory in the available field. For example, if your program was built in the C:/source1 directory and the source is available in the C:/source2 directory, enter C:/source2 in the first field and associate it with C:/source1 using the second field.

    If you want the IDE to recurse down the directories you pointed it at to find the source, then choose the Search subfolders option.

  3. Click Finish. The IDE adds the new source location.

Common tab

The Common tab lets you define where the launch configuration is stored, how you access it, and what perspective you change to when you launch.

Launch - Common tab

Type of launch configuration
When you create a launch configuration, the IDE saves it as a .launch file. If you select Local, the IDE stores the configuration in one of its own plugin directories. If you select Shared file, you can save it in a location you specify (such as in your project). Saving as a shared file lets you commit the .launch file to CVS, which allows others to run the program using the same configuration.
Display in favorites
You can have your launch configuration displayed when you click the Run or Debug dropdown menus in the toolbar. To do so, check the Run or Debug options under the Display in favorites menu heading.
Launch in background
This is enabled by default, letting the IDE launch applications in the background. This lets you continue to use the IDE while waiting for a large application to be transferred to the target and start.

Tools tab

The Tools tab lets you add runtime analysis tools to the launch. To do this, click the Add/Delete Tool button at the bottom of the tab:

Launch Configurations dialog; tools tab

You can add the following tools (some launch options affect which tools are available):

Application Profiler
Lets you count how many times functions are called, who called which functions, and so on. For more information about this tool, see the Profiling Your Application chapter.

Application Profiler

Memory Analysis
Lets you track memory errors. For more information about this tool, see the Finding Memory Errors chapter.

Memory Analysis

Code Coverage
Lets you measure what parts of your program have run, and what parts still need to be tested. For more information about this tool, see the Code Coverage chapter.

Code Coverage

If you want the IDE to open the appropriate perspective for the tool during the launch, then check Switch to this tool's perspective on launch.