diff options
Diffstat (limited to 'doc/org.eclipse.cdt.doc.user/raw/hackedguide/lnch.html')
| -rw-r--r-- | doc/org.eclipse.cdt.doc.user/raw/hackedguide/lnch.html | 457 |
1 files changed, 457 insertions, 0 deletions
diff --git a/doc/org.eclipse.cdt.doc.user/raw/hackedguide/lnch.html b/doc/org.eclipse.cdt.doc.user/raw/hackedguide/lnch.html new file mode 100644 index 00000000000..f86b9bbb092 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/raw/hackedguide/lnch.html @@ -0,0 +1,457 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.ord/TR/html4/loose.dtd"> +<html> + +<head> + +<title>Starting Your Programs (launcher)</title> + +</head> +<body bgcolor="#ffffff" text="#000000"> +<hr> + + +<h1><a name="id1">Starting Your Programs (launcher)</a></h1> + +<p> + + +</p> +<p>Before running or debugging a program, you must configure how and where to +run it, and what options to pass to it. To do all this, you must use the +launcher. + +</p> +<p></p> + +In this chapter: +<ul> +<li><a href="#lnch_works">How the launcher works</a> + </li> +<li><a href="#lnch_diff">Differences between launch configurations</a> + </li> +<li><a href="#lnch_run1">Running and debugging the first time (Launch Configuration dialog)</a> + </li> +<li><a href="#lnch_run2">Running and debugging subsequent times (Launch Configuration dialog)</a> + </li> +<li><a href="#lnch_tabs">Setting execution options (Launch Configuration tabs)</a></li> +</ul> + +<h1><a name="lnch_works">How the launcher works</a></h1> + +<p>To run or debug programs with the IDE, you must set up a <i>launch +configuration</i>. Launch configurations define which programs to launch, +the command-line options to use, and what values to use for environment +variables. </p> +<p> + +The IDE saves your launch configurations so you can quickly reproduce the +execution conditions by running existing configurations, even if the setup +is complicated.</p> + +<h1><a name="lnch_diff">Types of launch configurations</a></h1> + +<p>The IDE supports these types of launch configurations: + +</p> +<dl> + +<dt><b>C/C++ Local</b></dt> +<dd>If you're developing on your target (self-hosted), you may create a <b>C/C++ Local</b> launch configuration. You don't need to use <tt>qconn</tt>; the IDE launches your program through <a href="../../neutrino/utilities/g/gdb.html"><tt>gdb</tt></a>. + +</dd> +<dt><b>C/C++ Postmortem debugger</b></dt> +<dd>If your program produced a corefile (via the <a href="../../neutrino/utilities/d/dumper.html"><tt>dumper</tt></a> 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 <b>Debug</b>. When you debug, you're prompted with the <b>Select the corefile</b> dialog. + +</dd> +</dl> + +</p> + +<h1><a name="lnch_run1">Running and debugging the first time (Launch Configurations dialog)</a></h1> + +<p>You can use the same launch configuration to run or debug a program. Your choices in the <b>Launch Configurations</b> dialog may +cause subtle changes in the dialog but greatly affect such things as which options in the +dialog are enabled. + +<h2><a name="id6">Enabling the Run and Debug menu items</a></h2> + +<p>The <b>Run</b> and <b>Debug</b> menu items appear in the <b>C/C++ Development</b> perspective by default, but they might not appear in all perspectives. It's also possible to remove them. If the <b>Run</b>--><b>Run</b> menu item doesn't appear, you must enable it. + +</p> +<p>To enable the <b>Run</b> and <b>Debug</b> menu items:</p> +<ol> + +<li>From the main menu, select <b>Window</b>--><b>Customize Perspective</b>. + The <b>Customize Perspective</b> dialog appears. + </li> +<li>In the left pane, select <b>Other</b>--><b>Launch</b>. + </li> +<li>Enable <b>Launch</b>: + <p><img src="./images/lnch_customize.jpg" alt="Launch Configuration dialog; customization"> + </p></li> +<li>Click <b>OK</b>. + The <b>Run</b>--><b>Run</b> menu item is now accessible in your current perspective.</li> +</ol> + + +<h2><a name="debug_first">Debugging a program the first time</a></h2> + +<p>When you first debug a program, you have to create a launch configuration.</p> +<p> + +To debug a program the first time:</p> +<ol> + +<li>In the <b>C/C++ Projects</b> view (or the <b>Navigator</b> view), select your project. + </li> +<li>From the main menu, select <b>Run</b>--><b>Debug</b> (or, click the <b>Debug</b> icon and select <b>Debug</b> from the dropdown menu): + <p><img src="./images/lnch_debug_debug.jpg" alt="Launch Configuration dialog; debugging"> + </p></li> +<li>Select a launch configuration type: + <p><img src="./images/lnch.jpg" alt="Launch Configuration dialog"></p><p> If you're connecting to your target via IP, select <b>C/C++ QNX QConn (IP)</b>. If not, see the +<a href="#lnch_diff">"Types of Launch Configurations"</a> section in this chapter before deciding: + + </p></li> +<li>Click <b>New</b>. +The dialog displays the appropriate tabs + </li> +<li>Enter an appropriate description for your configuration in the <b>Name</b> field. + </li> +<li>Fill in the details in the various tabs. See the <a href="#lnch_tabs">"Setting execution options (Launch Configurations tabs)"</a> section in this chapter for details about each tab. + </li> +<li>Click <b>Debug</b>. + You can now debug your program.</li> +</ol> + + +<h2><a name="id9">Running a program the first time</a></h2> + +<p>When you configure a program to run, you should also configure it to debug as well. + +</p> + +<hr> +<table> +<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td> +<td>There are fewer options for running programs than for debugging. Some configurations aren't available.</td></tr> +</table> +<hr> + + +<p> + +To run a program the first time:</p> + +<table> +<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=>>"></td> +<td>Repeat the procedure for debugging a program (see <a href="#debug_first">"Debugging a program the first time"</a>), with the following changes: +<ul> +<li>Instead of selecting <b>Run</b>--><b>Debug</b> from the main menu, select <b>Run</b>--><b>Run</b> (or, click the <b>Run</b> icon and select <b>Run</b> from the dropdown menu): + <p><img src="./images/lnch_run_run.jpg" alt="Launch Configuration dialog; running"> + </p></li> +<li>Instead of clicking <b>Debug</b> when you're done, click <b>Run</b>. + </li> +<li>Instead of running under the control of a debugger, your program runs.</li> +</ul></td></tr> +</table> + + + +<h1><a name="lnch_run2">Running and debugging subsequent times (Launch Configurations dialog)</a></h1> + +<p>Once you've created your launch configuration, running or debugging a program is as easy as selecting your previous configuration. There are several ways to do it:</p> +<ul> +<li>fast way: see <a href="#fast">"Launching a selected program"</a> + </li> +<li>faster way: see <a href="#faster">"Launching from a list of favorites"</a> + </li> +<li>fastest way: see <a href="#fastest">"Launching the last-launched program"</a></li> +</ul> + +<h2><a name="fast">Launching a selected program</a></h2> + +<p> + +To debug or run a program that you've created a launch configuration for:</p> +<ol> + +<li>From the main menu, select <b>Run</b>--><b>Debug</b> or <b>Run</b>--><b>Run</b>. + The <b>Launch Configurations</b> dialog appears. + </li> +<li>In the left pane, select the launch configuration you created when you first ran or debugged your program. + </li> +<li>Click <b>Debug</b> or <b>Run</b>. + </li> +</ol> + + +<h2><a name="faster">Launching from a list of favorites</a></h2> + +<p>If you have a program that you launch frequently, you can add it to the <b>Debug</b> or <b>Run</b> drop-down menu so you can launch it quickly.</p> +<p></p> + +<hr> +<table> +<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td> +<td>To use this method, you must have selected <b>Display in favorites</b> when you first created your Launch Configuration. If you didn't, edit the <b>Display in favorites</b> option under the <b>Common</b> tab. See the <a href="#lnch_tabs">"Setting execution options (Launch Configurations tabs)"</a> section in this chapter.</td></tr> +</table> +<hr> + + +<p>To debug or run a program using your favorites list:</p> +<ol> + +<li>Do one of the following: + <ul> +<li>Run: From the main menu, select <b>Run</b>--><b>Run History</b>. + </li> +<li>Run: Click the dropdown menu <img src="./images/icon_menu.gif" alt="Icon: Menu dropdown"> part of the run menu button set <img src="./images/icon_run_exc.gif" alt="Icon: Run"><img src="./images/icon_menu.gif" alt="Icon: Menu dropdown">. + </li> +<li>Debug: From the main menu, select <b>Run</b>--><b>Debug History</b>. + </li> +<li>Debug: Click the dropdown menu <img src="./images/icon_menu.gif" alt="Icon: Menu dropdown"> part of the debug menu button set <img src="./images/icon_debug_exc.gif" alt="Icon: Debug"><img src="./images/icon_menu.gif" alt="Icon: Menu dropdown">. + </li> +</ul> + A list appears, showing all the launch configurations for which you enabled <b>Display in favorites</b>: + <p><img src="./images/lnch_run2_faster.jpg" alt="Launch Configuration dialog; running a program subsequent times (faster)"> + + </p></li> +<li>Select your launch configuration.</li> +</ol> + + +<h2><a name="fastest">Launching the last-launched program</a></h2> + +<p>To relaunch the last program you ran or debugged:</p> +<p></p> + +<table> +<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=>>"></td> +<td>Press <font face="Helvetica"><b>F11</b></font> or click one of: +<ul> +<li> the <b>Debug Last Launched: <i>yourLaunchName</i></b> button +<img src="./images/icon_debug_exc.gif" alt="Icon: Debug"> + </li> +<li> the <b>Run Last Launched: <i>yourLaunchName</i></b> +<img src="./images/icon_run_exc.gif" alt="Icon:Run"></li> +</ul></td></tr> +</table> + + + +<h1><a name="lnch_tabs">Setting execution options (Launch Configurations tabs)</a></h1> + +<p>The <b>Launch Configurations</b> dialog has many tabs, including:</p> +<p></p> +<ul> +<li><a href="#tab_main"><b>Main</b> tab</a> + </li> +<li><a href="#tab_arguments"><b>Arguments</b> tab</a> + </li> +<li><a href="#tab_environment"><b>Environment</b> tab</a> + </li> +<li><a href="#tab_debugger"><b>Debugger</b> tab</a> + </li> +<li><a href="#tab_common"><b>Common</b> tab</a> + </li> +</ul> +<p>Depending on what type of launch configuration you've selected, only certain tabs appear:</p> +<p></p> +<table border=1 width="100%"> + +<tr> +<th><b>Launch Configuration</b> + </th> +<th><b>Main</b> tab,<br> + <b>Common</b> tab + + </th> +<th><b>Arguments</b> tab,<br> + <b>Environment</b> tab + </th> +<th><b>Debugger</b> tab + </th> +</tr> +<tr> +<td><b>C/C++ Local</b> + </td> +<td>Yes + </td> +<td>Yes + </td> +<td>Yes + </td> +</tr> +<tr> +<td><b>C/C++ Postmortem debug</b>*** + </td> +<td>Yes + </td> +<td>No + </td> +<td>Yes + </td> +</tr> +</table> + +<p>***<b>Debug</b> only; core file required.</p> +<p> + + +</p> + +<h2><a name="tab_main">Main tab</a></h2> + +<p>This tab lets you specify the project and program that you want to run or debug. The IDE might fill in some of the fields for you:</p> +<p><img src="./images/lnch_main.jpg" alt="Launch Configurations dialog; Main tab"></p> +<p> + +The <b>Main</b> tab varies, depending on the type of configuration you're creating. If you're creating a <b>C/C++ QNX QConn (IP)</b> launch configuration, you'll see a section for <b>Target Options</b>; for <b>C/C++ PDebug (Serial)</b>, you'll see <b>Serial Options</b>. + +</p> +<dl> + +<dt><b>Project</b></dt> +<dd>Enter the name of your project. You may also select from the open projects by clicking <b>Browse</b>. You can create or edit launch configurations only for open projects. + +</dd> +<dt><b>C/C++ Application</b></dt> +<dd>Enter the relative path of the executable from the project directory (e.g. <tt>x86/o/KillerApp</tt>). +For <b>QNX</b> projects, an executable with a <tt>_g</tt> suffix indicates it was compiled for debugging. +You may also select from the available executables by clicking <b>Search</b>. + +</dd> +<dt><b>Target Options</b></dt> +<dd>You'll see this section only for <b>C/C++ QNX QConn (IP)</b> launch configurations. +Select a target from the available list. If you haven't created a target, right-click the empty pane and select <b>Add Target</b>. For more information about creating a target, see the <a href="cwiz.html">Common Wizards</a> chapter. + +</dd> +<dt><b>Filter targets based on C/C++ Application selection</b></dt> +<dd>Enable this option to hide platforms that don't match your chosen executable. For example, if you've chosen a program compiled for PPC, you'll see only PPC targets. + +</dd> +<dt><b>Serial Options</b></dt> +<dd>You'll see this section only for <b>C/C++ QNX PDebug (Serial)</b> launch configurations. + +</dd> +<dt><b>Serial Port</b></dt> +<dd>Enter the communication port (e.g. <tt>COM1</tt> for Windows; <tt>/dev/ser1</tt> for QNX Neutrino). + +</dd> +<dt><b>Baud Rate</b></dt> +<dd>Select the baud rate from the dropdown list.</dd> +</dl> + + +<h2><a name="tab_arguments">Arguments tab</a></h2> + +<p>This tab lets you specify the arguments your program uses and the directory where it runs:</p> +<p><img src="./images/lnch_arguments.jpg" alt="Launch Configurations dialog; Arguments tab"> + +</p> +<dl> + +<dt><b>C/C++ Program Arguments</b></dt> +<dd>Enter the arguments that you want to pass on the command line. For example, if you want to send the equivalent of <tt><i>myProgram</i> <tt><b>-v</b></tt> <tt><b>-L 7</b></tt></tt>, type <tt><b>-v -L 7</b></tt> in this field. You can put <tt><b>-v</b></tt> and <tt><b>-L 7</b></tt> on separate lines because the IDE automatically strings the entire contents together. + +</dd> +<dt><b>Working directory</b></dt> +<dd>Enable <b>Use default working directory</b> to run the executable from the directory where the IDE is running. If you disable <b>Use default working directory</b>, you can specify a full path in the <b>Local directory</b> field or a relative path in the <b>Workspace</b> field.</dd> +</dl> + + +<h2><a name="tab_environment">Environment tab</a></h2> + +<p>The <b>Environment</b> tab lets you set the environment variables and values to use when the program launches:</p> +<p><img src="./images/lnch_environment.jpg" alt="Launch Configurations dialog; Environment tab"></p> +<p> For example, if you want to set the environment variable named <b>PHOTON</b> to the value <tt>/dev/photon_2</tt> when you run your program, use this tab. Click <b>New</b> to add an environment variable.</p> + +<h2><a name="tab_debugger">Debugger tab</a></h2> + +<p>The <b>Debugger</b> tab lets you choose which debugger to use when you debug your program:</p> +<p><img src="./images/lnch_debugger.jpg" alt="Launch Configurations dialog; Debugger tab"></p> + +<hr> +<table> +<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td> +<td>The settings in the <b>Debugger</b> tab affect the program only when you debug it, not when you run it.</td></tr> +</table> +<hr> + + +<dl> + +<dt><b>Debugger</b></dt> +<dd>The debugger dropdown list includes the available debuggers for the selected launch-configuration type. The list also varies depending on whether you're debugging self-hosted. + +</dd> +<dt><b>Run program in debugger</b>/<b>Attach to running process</b></dt> +<dd>Most of the time, you'll want to simply <b>Run program in debugger</b>. +If you enable <b>Attach to running process</b>, you're prompted to select a process from a list at run time. Note the following limitations: + + <ul> +<li>You can attach only to programs that you launched for debugging. + </li> +<li>You can't use the <b>Memory Trace</b> tool. + </li> +</ul></dd> +<dt><b>Stop at main() on startup</b></dt> +<dd>If you deselect <b>Stop at main() on startup</b>, the program runs until you interrupt it manually, or until it hits a breakpoint. + +</dd> +<dt><b>Debugger Options</b></dt> +<dd>You'll see this section only for <b>C/C++ Local</b> launch configurations; the IDE already automatically fills in the options for <b>QNX</b> launch configurations. + + <dl> + +<dt><b>MI Debugger</b> + </dt> +<dd>You can choose the MI (Machine Interface) Debugger, such as the <tt>gdb</tt> executable. + + </dd> +<dt><b>Load shared library symbols automatically</b> + </dt> +<dd>If you want to watch line-by-line stepping of library functions in the <b>C Editor</b>, enable this option. You may wish to disable this option if your target doesn't have much memory; the library symbols take up RAM on the target. It's enabled by default. + </dd> +</dl> +</dd> +</dl> + + +<h2><a name="tab_common">Common tab</a></h2> + +<p>The <b>Common</b> tab lets you define where the launch configuration is stored, how you access it, and what perspective you change to when you launch:</p> +<p><img src="./images/lnch_common.jpg" alt="Launch Configurations dialog; Common tab"> + + +</p> +<dl> + +<dt><b>Type of launch configuration</b></dt> +<dd>When you create a launch configuration, the IDE saves it as a <tt>.launch</tt> file. If you select <b>Local</b>, the IDE stores the configuration in one of its own plugin directories. If you select <b>Shared</b>, you can save it in a location you specify (such as in your project). Saving as <b>Shared</b> lets you commit the <tt>.launch</tt> file to CVS so your coworkers can run the program using the same configuration. + +</dd> +<dt><b>Perspective to switch to or open when launched in</b></dt> +<dd>You can configure which perspectives the IDE changes to when you run or debug. You can set the perspectives specifically, or simply set them to <b>Default</b>. To determine the default perspectives for both, select <b>Window</b>--><b>Preferences</b> from the main menu and select <b>Debug</b> from the left pane. + +</dd> +<dt><b>Display in favorites</b></dt> +<dd>You can have your launch configuration displayed when you click the <b>Run</b> or <b>Debug</b> dropdown menus. To do so, enable <b>Run</b> or <b>Debug</b> under the <b>Display in favorites menu:</b> heading.</dd> +</dl> + +</body> + +</html> + +<!-- +/********************************************************************** + * Copyright (c) 2002,2003 QNX Software Systems Ltd. and others. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Common Public License v0.5 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/cpl-v05.html + * + * Contributors: + * QNX Software Systems - Initial API and implementation +***********************************************************************/ +--> |