This is gps.info, produced by makeinfo version 4.0 from gps.texi.


File: gps.info,  Node: Searching and Replacing,  Next: Compilation/Build,  Prev: Project Handling,  Up: Top

Searching and Replacing
***********************

GPS provides extensive search capabilities among its different
elements. For instance, it is possible to search in the currently
edited source file, or in all the source files belonging to the
project, even those that are not currently open. It is also possible to
search in the project explorer (on the left side of the main GPS
window), or the help modules,...

   All these search contexts are grouped into a single graphical window,
that you can open either through the menu `Navigate->Find/Replace...',
or the shortcut <Ctrl-F>.

   Selecting either of these two options will pop up a dialog on the
screen, similar to the following:

   On this screen shot, you can see three entry fields:

`Search for'
     This is the location where you type the string or pattern you are
     looking for. The search widget supports two modes, either fixed
     strings or regular expressions. You can commute between the two
     modes by either clicking on the `Options' button and selecting the
     appropriate check box, or by opening the combo box (click on the
     arrow on the right of the entry field).

     In this combo box, a number of predefined patterns are provided.
     The top two ones are empty patterns, that automatically set up the
     appropriate fixed strings/regular expression mode. The other
     regular expressions are language-specific, and will match patterns
     like Ada type definition, C++ method declaration,...

`Replace with'
     This field should contain the string that will replace the
     occurrences of the pattern defined above.  The combo box provides
     a history of previously used replacement strings.

`Look in'
     This field defines the context in which the search should occur.
     Clicking on the arrow on the right will display the list of all
     possible contexts. The exact list will depend on what modules were
     loaded by GPS, since each module can add its own contexts.

     Depending on the selected context, extra fields might be displayed
     on the screen. For instance, if you select the context `Files...'
     you will be asked what files or directories should be searched.
     These are regular expressions.

     When searching one or more source files, an extra field to select
     the scope is provided. This is used to avoid matching on comments
     when you are only interested in actual code, or to only search
     strings and comments, and ignore the code.

     GPS will automatically select the most appropriate context when you
     open the search dialog, depending on which component currently has
     the focus. You can of course change the context to another one if
     needed.

   The second part of the window is a row of buttons, to start the
search (or continue to the next occurrence), to stop the current search
when it is taking too long, or to display the options.

   There are four check boxes in this options box.

`"Search All Occurrences"'
     The default mode for the search widget is interactive searching:
     its stops as soon as one occurrence of the pattern is found. You
     then have to press the `Next' button (or the equivalent shortcut
     <Ctrl-N>) to go to the next occurrence.

     However, if you enable this check box, the search widget will start
     searching for all occurrences right away, and put the results in a
     new window called `Locations' (initially found in the bottom dock
     of the GPS window). You can interrupt the search at any time by
     pressing the `Stop' button: this will stop when the next
     occurrence is found.

`"Case Sensitive"'
     By default, patterns are case insensitive (upper-case letters and
     lower-case letters are considered as equivalent). You can change
     this behavior by clicking on this check box.

`"Whole Word Only"'
     If activated, this check box will force the search engine to ignore
     substrings. "sensitive" will no longer match "insensitive".

`"Regular Expression"'
     This button commutes between fixed string patterns and regular
     expressions. As mentioned above, you can also commute between
     these two modes by selecting the arrow on the right of the `Search
     for:' field.

   As most GPS components, the search window is under control of the
multiple document interface, and can thus be integrated into the main
GPS window instead of being an external window.

   To force this behavior, open the menu `Window', select `Search' in
the list at the bottom of the menu, and then select either `Floating'
or `Docked'.

   If you save the desktop (`File->Save...->Desktop', GPS will
automatically reopen the search dialog in its new place when it is
started next time.


File: gps.info,  Node: Compilation/Build,  Next: Source Browsing,  Prev: Searching and Replacing,  Up: Top

Compilation/Build
*****************

This chapter describes how to compile files, build executables and run
them. Most capabilities can be accessed through the `Build' menu item,
or through the `Build' and `Run' contextual menu items, as described in
the following section.

   When compiler messages are detected by GPS, an entry is added in the
Locations tree, allowing you to easily navigate through the compiler
messages (see *Note The Locations Tree::), or even to automatically
correct some errors or warnings (see *Note Code Fixing::).

* Menu:

* The Build Menu::
* Integrating existing build procedures with the GPS build system::


File: gps.info,  Node: The Build Menu,  Next: Integrating existing build procedures with the GPS build system,  Up: Compilation/Build

The Build Menu
==============

The build menu gives access to capabilities related to checking,
parsing and compiling files, as well as creating and running
executables.

Check Syntax
     Check the syntax of the current source file. Display an error
     message in the Messages window if no file is currently selected.
     This option is currently only supported for Ada files.

Compile File
     Compile the current file. Display an error message in the Messages
     window if no file is selected.

     If errors or warnings occur during the compilation, the
     corresponding locations will appear in the Locations Tree. If the
     corresponding Preference is set, the source lines will be
     highlighted in the editors (see *Note The Preferences Dialog::).
     To remove the highlighting on these lines, remove the files from
     the Locations Tree.

     This option is currently only supported for Ada files.

Make

    main
          For each main source file defined in your top level project,
          an entry    is listed to build (compile, bind, link) this
          source file.     Similarly the `Build' contextual menu
          accessible from a project    entity contains the same entries.

    <current file>
          Consider the currently selected file as a main file, and
          build it.

    All main subprograms
          Build all main files defined in your top level project.

    Custom...
          Display a text entry where you can enter any external
          command. This menu    is very useful when you already have
          existing build scripts, make files,    ... and want to invoke
          them from GPS.

Recompute C/C++ Xref info
     Recompute the cross reference information for C and C++ source
     files.  *Note Support for Cross References::.

Run

    main
          For each main source file defined in your top level project,
          an entry    is listed to run the executable associated with
          this main file.     Running an application will first open a
          dialog where you can specify    command line arguments to
          your application, if needed. You can also    specify whether
          the application should be run within GPS (the default),    or
          using an external terminal.

          When running an application from GPS, a new execution window
          is added in the    bottom area where input and output of the
          application is handled. This    window is never closed
          automatically, even when the application terminates,    so
          that you can still have access to the application's output.
          If you    explicitly close an execution window while an
          application is still running,    a dialog window will be
          displayed to confirm whether the application should    be
          terminated.

          When using an external terminal, GPS launches an external
          terminal    utility that will take care of the execution and
          input/output of your    application. This external utility
          can be configured in the preferences    dialog
          (Helpers->Execute command).

          Similarly, the `Run' contextual menu accessible from a project
            entity contains the same entries.

    Custom...
          Similar to the entry above, except that you can run any
          arbitrary executable.

Interrupt
     Interrupt the current compilation or build.


File: gps.info,  Node: Integrating existing build procedures with the GPS build system,  Prev: The Build Menu,  Up: Compilation/Build

Integrating existing build procedures with the GPS build system
===============================================================

Note that this capability is not fully supported yet.

   Since the multi-language build system provided by GPS is based on
makefiles, it is possible to integrate existing build scripts and
makefiles. In the following section, we will call such projects that
integrate with existing build procedures a foreign project.

   You first need to provide your own `Makefile.<project>' file, that
will provide stubs to the real build commands.

   Then to tell GPS that it should not generate automatically the
makefile corresponding to a given project, set the read-only attribute
on the makefile, e.g under Unix:

     $ chmod -w Makefile.<project>

   or under Windows:

     > attrib +r Makefile.<project>

   This way when saving the project, GPS knows that the existing
makefile should not be overridden.

   Depending on your project, you will need to define some or all of the
following targets in the makefile stub:

internal-build
     This is the main rule, used for building all the files for a
     foreign project.

internal-clean
     This is an optional rule, used to clean the temporary files, e.g.
     the object files generated during the build.

SRC_DIRS
     Blank separated list of source directories.

LDFLAGS
     Linker options.

LIBS
     Additional libraries that this foreign project uses.

DEPS_PROJECTS
     List of projects (foreign or non foreign) that this project
     depends upon.

   For example, suppose we have a foreign project called `Foo', with an
existing makefile, here is how Makefile.foo would look like:

     ifeq ($(FOO_PROJECT),)
     FOO_PROJECT=True
     
     ifeq ($(BASE_DIR),)
        BASE_DIR=$(shell pwd)
        FOO_ROOT=True
     
     # Redirect clean to the real clean rule
        internal-clean:
             $(MAKE) clean
     
     # Ditto for the build rule
        internal-build:
             $(MAKE) build
     endif
     
     FOO_BASE_DIR := $(BASE_DIR)
     
     # Add our source directories to the default search path
     # so that other projects can reference our include files
     FOO_SRC_DIRS = $(FOO_BASE_DIR)/include $(FOO_BASE_DIR)/include2
     SRC_DIRS += $(FOO_SRC_DIRS)
     
     # Add <build>/libfoo.a, built by the internal-build rule above, to the
     # list of libraries to link with
     LIBS := $(FOO_BASE_DIR)/<build>/libfoo.a $(LIBS)
     
     ifneq ($(FOO_ROOT),True)
        DEPS_PROJECTS += $(FOO_BASE_DIR)/foo
     endif
     
     endif


File: gps.info,  Node: Source Browsing,  Next: Debugging,  Prev: Compilation/Build,  Up: Top

Source Browsing
***************

* Menu:

* General Issues::
* Call Graph::
* Dependency Browser::
* Entity Browser::


File: gps.info,  Node: General Issues,  Next: Call Graph,  Up: Source Browsing

General Issues
==============

GPS contains several kinds of browsers, that have a common set of basic
functionalities. There are currently four such browsers: the project
browser (*note The Project Browser::), the call graph (*note Call
Graph::), the dependency browser (*note Dependency Browser::) and the
entity browser (*note Entity Browser::).

   All these browsers are interactive viewers. They contain a number of
items, whose visual representation depends on the type of information
displayed in the browser (they can be projects, files, entities, ...).

   In addition, the following capabilities are provided in all browsers:

Scrolling
     When a lot of items are displayed in the canvas, the currently
     visible area might be too small to display all of them. In this
     case, scrollbars will be added on the sides, so that you can make
     other items visible. Scrolling can also be done with the arrow
     keys.

Layout
     A basic layout algorithm is used to organize the items. This
     algorithm is layer oriented: items with no parents are put in the
     first layer, then their direct children are put in the second
     layer, and so on. Depending on the type of browser, these layers
     are organized either vertically or horizontally. This algorithm
     tries to preserve as much as possible the positions of the items
     that were moved interactively.

     The `refresh layout' menu item in the background contextual menu
     can be used to recompute the layout of items at any time, even for
     items that were previously moved interactively.

Interactive moving of items
     Items can be moved interactively with the mouse. Click and drag the
     item by clicking on its title bar. The links will still be
     displayed during the move, so that you can check whether it
     overlaps any other item. If you are trying to move the item
     outside of the visible part of the browser, the latter will be
     scrolled.

Links
     Items can be linked together, and will remain connected when items
     are moved. Different types of links exist, see the description of
     the various browsers.

     By default, links are displayed as straight lines. You can choose
     to use orthogonal links instead, which are displayed only with
     vertical or horizontal lines. Select the entry `orthogonal links'
     in the background contextual menu.

Zooming
     Several different zoom levels are available. The contextual menu in
     the background of the browser contains three entries: `zoom in',
     `zoom out' and `zoom'. The latter is used to select directly the
     zoom level you want.

     This zooming capability is generally useful when lots of items are
     displayed in the browser, to get a more general view of the layout
     and the relationships between the items.

Selecting items
     Items can be selected by clicking inside them. Multiple items can
     be selected by holding the <control> key while clicking in the
     item. Alternatively, you can click and drag the mouse inside the
     background of the browser. All the items found in the selection
     rectangle when the mouse is released will be selected.

     Selected items are drawn with a different title bar color. All
     items linked to them also use a different title bar color, as well
     as the links. This is the most convenient way to understand the
     relationships between items when lots of them are present in the
     browser.

Hyper-links
     Some of the items will contain hyper links, displayed in blue by
     default, and underlined. Clicking on these will generally display
     new items.

   Two types of contextual menus are available in the browsers: the
background contextual menu is available by right-clicking in the
background area (i.e. outside of any item). As described above, it
contains entries for the zooming, selecting of orthogonal links, and
refresh; the second kind of contextual menu is available by
right-clicking in items.

   The latter menu contains various entries. Most of the entries are
added by various modules in GPS (VCS module, source editor, ...). In
addition, each kind of browser also has some specific entries, which is
described in the corresponding browser's section.

   There are two common items in all item contextual menus:

`Hide Links'
     Browsers can become confusing if there are many items and many
     links. You can lighten them by selecting this menu entry. As a
     result, the item will remain in the canvas, but none of the links
     to or from it will be visible. Selecting the item will still
     highlight linked items, so that this information remains available.

`Remove all other items'
     Selecting this menu item will remove all items but the selected
     one.


File: gps.info,  Node: Call Graph,  Next: Dependency Browser,  Prev: General Issues,  Up: Source Browsing

Call Graph
==========

The call graph shows graphically the relationship between subprogram
callers and callees. A link between two items indicate that one of them
is calling the other.

   A special handling is provided for renaming entities (in Ada): if a
subprogram is a renaming of another one, both items will be displayed
in the browser, with a special hashed link between the two. Since the
renaming subprogram doesn't have a proper body, you will then need to
ask for the subprograms called by the renamed to get the list.

   In this browser, clicking on the right arrow in the title bar will
display all the entities that are called by the selected item.

   Clicking on the left arrow will display all the entities that call
the selected item (i.e. its callers).

   This browser is accessible through the contextual menu in the project
explorer and source editor, by selecting one of the items:

`References->Entity calls'
     Display all the entities called by the selected entity. This has
     the same effect as clicking on the right title bar arrow if the
     item is already present in the call graph.

`References->Entity is called by'
     Display all the entities called by the selected entity. This has
     the same effect as clicking on the left title bar arrow if the
     item is already present in the call graph.

   The contextual menu available by right-clicking on the entities in
the browser has the following new entries, in addition to the ones
added by other modules of GPS.

`Entity calls'
     Same as described above.

`Entity is called by'
     Same as described above.

`Go To Spec'
     Selecting this item will open a source editor that displays the
     declaration of the entity.

`Go To Body'
     Selecting this item will open a source editor that displays the
     body of the entity.

`Locate in explorer'
     Selecting this menu entry will move the focus to the project
     explorer, and select the first node representing the file in which
     the entity is declared. This makes it easier to see which other
     entities are declared in the same file.


File: gps.info,  Node: Dependency Browser,  Next: Entity Browser,  Prev: Call Graph,  Up: Source Browsing

Dependency Browser
==================

The dependency browser shows the dependencies between source files.
Each item in the browser represents one source file.

   In this browser, clicking on the right arrow in the title bar will
display the list of files that the selected file depends on. A file
depend on another one if it explicitly imports it (`with' statement in
Ada, or `#include' in C/C++). Implicit dependencies are currently not
displayed in this browser, since the information is accessible by
opening the other direct dependencies.

   Clicking on the left arrow in the title bar will display the list of
files that depend on the selected file.

   This browser is accessible through the contextual menu in the
explorer, by selecting one of the following items:

`Show dependencies for file'
     This has the same effect as clicking on the right arrow for a file
     already in the browser, and will display the direct dependencies
     for that file.

`Show files depending on file'
     This has the same effect as clicking on the left arrow for a file
     already in the browser, and will display the list of files that
     directly depend on that file.

   The background contextual menu in the browser adds a few entries to
the standard menu:

`Open file...'
     This menu entry will display an external dialog in which you can
     select the name of a file to analyze.

`Refresh'
     This menu entry will check that all links displays in the
     dependency browser are still valid. If not, they are removed. The
     arrows in the title bar are also reset if necessary, in case new
     dependencies were added for the files.

     The browser is not refreshed automatically, since there are lots of
     cases where the dependencies might change (editing source files,
     changing the project hierarchy or the value of the scenario
     variables,...)

`Show system files'
     This menu entry indicates whether standard system files (runtime
     files for instance in the case of Ada) are displayed in the
     browser. By default, these files will only be displayed if you
     explicitly select them through the `Open file' menu, or the
     contextual menu in the project explorer.

`Show implicit dependencies'
     This menu entry indicates whether implicit dependencies should
     also be displayed for the files. Implicit dependencies are files
     that are required to compile the selected file, but that are not
     explicitly imported through a `with' or `#include' statement. For
     instance, the body of generics in Ada is an implicit dependency.
     Any time one of the implicit dependencies is modified, the selected
     file should be recompiled as well.

   The contextual menu available by right clicking on an item also adds
a number of entries:

`Analyze other file'
     This will open a new item in the browser, displaying the complement
     file for the selected one. In Ada, this would be the body if you
     clicked on a spec file, or the opposite. In C, it depends on the
     naming conventions you specified in the project properties, but you
     would generally go from a `.h' file to a `.c' file and back.

`Show dependencies for file'
     These play the same role as in the project explorer contextual menu


File: gps.info,  Node: Entity Browser,  Prev: Dependency Browser,  Up: Source Browsing

Entity Browser
==============

The entity browser displays static information about any source entity.

   The exact content of the items depend on the type of the item. For
instance:

`Ada record / C struct'
     The list of fields, each as an hyper link, is displayed. Clicking
     on one of the fields will open a new item for the type.

`Ada tagged type / C++ class'
     The list of attributes and methods is displayed. They are also
     click-able hyper-links.

`Subprograms'
     The list of parameters is displayed

`Packages'
     The list of all the entities declared in that package is displayed

`and more ...'
   This browser is accessible through the contextual menu in the
explorer, when clicking on an entity:

`Examine entity entity'
     Open a new item in the entity browser that displays information for
     the selected entity.

   Most information in the items are click-able (by default, they
appear as underlined blue text). Clicking on one of these hyper links
will open a new item in the entity browser for the selected entity.

   This browser can display the parent entities for an item. For
instance, for a C++ class or Ada tagged type, this would be the types
it derives from. This is accessible by clicking on the up arrow in the
title bar of the item.

   Likewise, children entities (for instance types that derive from the
item) can be displayed by clicking on the down arrow in the title bar.

   An extra button appear in the title bar for the C++ class or Ada
tagged types, which toggles whether the inherited methods (or primitive
operations in Ada) should be displayed. By default, only the new
methods, or the ones that override an inherited one, are displayed. The
parent's methods are not shown, unless you click on this title bar
button.


File: gps.info,  Node: Debugging,  Next: Version Control System,  Prev: Source Browsing,  Up: Top

Debugging
*********

GPS is also a graphical front-end for text-based debuggers such as GDB.
A knowledge of the basics of the underlying debugger used by GPS will
help understanding how GPS works and what kind of functionalities it
provides.

   Please refer to the debugger-specific documentation - e.g. the GDB
documentation - for more details.

   Debugging is tightly integrated with the other components of GPS. For
example, it is possible to edit files and navigate through your sources
while debugging.

   To start a debug session, go to the menu `Debug->Initialize', and
choose either the name of your executable, if you have specified the
name of your main program(s) in the project properties, or start an
empty debug session using the `<no main file>' item. It is then
possible to load any file to debug, by using the menu
`Debug->Debug->Load File...'

   After the debugger has been initialized, you have access to two new
windows: the data window (in the top of the working area), and the
debugger console (in a new page, after the Messages and Shell windows).
All the menus under `Debugger' are now also accessible, and you also
have access to additional contextual menus, in particular in the source
editor where it is possible to easily display variables, set
breakpoints, and get automatic display (via tool tips) of object values.

   When you want to quit the debugger without quitting GPS, go to the
menu `Debug->Terminate', which will terminate your debug session.

* Menu:

* The Debug Menu::
* The Call Stack Window::
* The Data Window::
* The Breakpoint Editor::
* The Memory Window::
* Using the Source Editor when Debugging::
* The Assembly Window::
* The Debugger Console::


File: gps.info,  Node: The Debug Menu,  Next: The Call Stack Window,  Up: Debugging

The Debug Menu
==============

The `Debug' entry in the menu bar provides operations that act at a
global level. Key shortcuts are available for the most common
operations, and are displayed in the menus themselves.  Here is a
detailed list of the menu items that can be found in the menu bar:

Run...
     Opens a dialog window allowing you to specify the arguments to
     pass to the program to be debugged, and whether this program
     should be stopped at the beginning of the main subprogram. If you
     confirm by clicking on the OK button, the program will be launched
     according to the arguments entered.

Step
     Execute the program until it reaches a different source line.

Step Instruction
     Execute the program for one machine instruction only.

Next
     Execute the program until it reaches the next source line,
     stepping over subroutine calls.

Next Instruction
     Execute the program until it reaches the next machine instruction,
     stepping over subroutine calls.

Finish
     Continue execution until selected stack frame returns.

Continue
     Continue execution of the program being debugged.

Interrupt
     Asynchronously interrupt the program being debugged. Note that
     depending on the state of the program, you may stop it in
     low-level system code that does not have debug information, or in
     some cases, not even a coherent state. Use of breakpoints is
     preferable to interrupting programs. Interrupting programs is
     nevertheless indispensable in some situations, for example when the
     program appears to be in an infinite (or at least very
     time-consuming) loop.

Terminate
     Terminate your debug session, by closing the data window and the
     debugger console, as well as terminating the underlying debugger
     (e.g `gdb') used to handle the low level debugging.

Debug
-----

Connect to Board...
     Opens a simple dialog to connect to a remote board. This option is
     only relevant to cross debuggers.

Load File...
     Opens a file selection dialog that allows you to choose a program
     to debug. The program to debug is either an executable for native
     debugging, or a partially linked module for cross environments
     (e.g VxWorks).

Add Symbols...
     Add the symbols from a given file/module. This corresponds to the
     gdb command add-symbol-file. This menu is particularly useful
     under VxWorks targets, where the modules can be loaded
     independently of the debugger.  For instance, if a module is
     independently loaded on the target (e.g. using windshell), it is
     absolutely required to use this functionality, otherwise the
     debugger won't work properly.

Attach...
     Instead of starting a program to debug, you can instead attach to
     an already running process. To do so, you need to specify the
     process id of the process you want to debug. The process might be
     busy in an infinite loop, or waiting for event processing. Note
     that as for *Note core files::, you need to specify an executable
     before attaching to a process.

Detach
     Detaches the currently debugged process from the underlying
     debugger.  This means that the executable will continue to run
     independently. You can use the Attach To Process menu later to
     re-attach to this process.

Debug Core File...
     This will open a file selection dialog that allows you to debug a
     core file instead of debugging a running process. Note that you
     must first specify an executable to debug before loading a core
     file.

Kill
     Kills the process being debugged.

Data
----

Note that most items in this menu need to access the underlying debugger
when the process is stopped, not when it is running. This means that
you first need to stop the process on a breakpoint or interrupt it,
before using the following commands. Failing to do so will result in
blank windows.

Call Stack
     Displays the Call Stack window.        See *Note The Call Stack
     Window:: for more details.

Threads
     Opens a new window containing the list of threads currently
     present in       the executable as reported by the underlying
     debugger. For each thread,       it will give information such as
     internal identifier, name and status.        This information is
     language- and debugger-dependent. You should refer to       the
     underlying debugger's documentation for more details.        As
     indicated above, the process being debugged needs to be stopped
       before using this command, otherwise a blank list will be
     displayed.

     When supported by the underlying debugger, clicking on a thread
     will       change the context (variables, call stack, source file)
     displayed,       allowing you to inspect the stack of the selected
     thread.

Tasks
     For GDB only, this will open a new window containing the list of
     Ada       tasks currently present in the executable. Similarly to
     the thread       window, you can switch to a selected task context
     by clicking on it, if       supported by GDB. See the GDB
     documentation for the list of       items displayed for each task.

     As for the thread window, the process being debugged needs to be
     stopped       before using this window.

Protection Domains
     For VxWorks AE only, this will open a new window containing the
       list of available protection domains in the target. To change
     to a       different protection domain, simply click on it. A
     indicates the current protection domain.

Assembly
     Opens a new window displaying an assembly dump of the current code
          being executed.        See *Note The Assembly Window:: for
     more details.

Edit Breakpoints
     Opens an advanced window to create and modify any kind of
     breakpoint       (see *Note The Breakpoint Editor::).        For
     simple breakpoint creation, see the description of the source
     window.

Examine Memory
     Opens a memory viewer/editor. See *Note The Memory Window:: for
     more       details.

Command History
     Opens a dialog with the list of commands executed in the current
     session.        You can select any number of items in this list
     and replay the selection       automatically.

Display Local Variables
     Opens an item in the Data Window containing all the local variables
          for the current frame.

Display Arguments
     Opens an item in the Data Window containing the arguments
     for the current frame.

Display Registers
     Opens an item in the Data Window containing the machine registers
         for the current frame.

Display Any Expression...
     Opens a small dialog letting you specify an arbitrary expression
        in the Data Window. This expression can be a variable name, or
     a       more complex expression, following the syntax of the
     underlying debugger.        See the documentation of e.g gdb for
     more details on the syntax.        The check button Expression is
     a subprogram call should be enabled       if the expression is
     actually a debugger       command (e.g `p/x var') or a procedure
     call in the program being       debugged (e.g `call my_proc').

Refresh
     Refreshes all the items displayed in the Data Window.


File: gps.info,  Node: The Call Stack Window,  Next: The Data Window,  Prev: The Debug Menu,  Up: Debugging

The Call Stack Window
=====================

The call stack window gives a list of frames corresponding to the
current    execution stack for the current thread/task.

   The bottom frame corresponds to the outermost frame where the thread
is    currently stopped. This frame corresponds to the first function
executed by the current thread (e.g main if the main thread is in C).
  You can click on any frame to switch to the caller's context, this
will    update the display in the source window. See also the up and
down    buttons in the tool bar to go up and down one frame in the call
stack.

   The contextual menu (right mouse button) allows you to choose which
 information you want to display in the call stack window (via check
buttons):
   * Frame number: the debugger frame number (usually starts at 0 or 1)

   * Program Counter: the low level address corresponding to the
         function's entry point.

   * Subprogram Name: the name of the subprogram in a given frame

   * Parameters: the parameters of the subprogram

   * File Location: the filename and line number information.

   By default, only the subprogram name is displayed.     You can hide
the call stack window by closing it, as for other windows, and    show
it again using the menu `Data->Call Stack'.


File: gps.info,  Node: The Data Window,  Next: The Breakpoint Editor,  Prev: The Call Stack Window,  Up: Debugging

The Data Window
===============

Description
-----------

The data window contains all the graphic boxes that can be accessed
using the Data->Display menu items, or the data window    Display
Expression... contextual menu, or the source window    Display
contextual menu items, or finally the    graph command in the debugger
console.

   For each of these commands, a box is displayed in the data window
with the following information:

   * A title bar containing:
        * The number of this expression: this is a positive number
          starting        from 1 and incremented for each new box
          displayed. It represents the        internal identifier of
          the box.

        * The name of the expression: this is the expression or variable
                specified when creating the box.

        * An icon representing either a flash light, or a lock.
          This is a click-able icon that will change the state of the
          box from        automatically updated (the flash light icon)
          to frozen (the lock        icon).         When frozen, the
          value is grayed, and will not change until you change
          the state. When updated, the value of the box will be
          recomputed each        time an execution command is sent to
          the debugger (e.g step, next).

        * An icon representing an 'X'.         You can click on this
          icon to close/delete any box.

   * A main area.       The main area will display the data value
     hierarchically      in a language-sensitive manner. The canvas
     knows about data structures      of various languages (e.g `C',
     `Ada', `C++') and will      organize them accordingly.       For
     example, each field of a record/struct/class, or each item of an
       array will be displayed separately. For each subcomponent, a
     thin box      is displayed to distinguish it from the other
     components.

   A contextual menu, that takes into account the current component
selected    by the mouse, gives access to the following capabilities:
Close component
     Closes the selected item.

Hide all component
     Hides all subcomponents of the selected item. To select a
     particular field or item in a record/array, move your mouse over
     the name of this component, not over the box containing the values
     for this item.

Show all component
     Shows all subcomponents of the selected item.

Clone component
     Clones the selected component into a new, independent item.

View memory at address of component
     Brings up the memory view dialog and explore memory at the address
     of the component.

Set value of component
     Sets the value of a selected component. This will open an entry box
     where you can enter the new value of a variable/component. Note
     that GDB does not perform any type or range checking on the value
     entered.

Update Value
     Refreshes the value displayed in the selected item.

Show Value
     Shows only the value of the item.

Show Type
     Shows only the type of each field for the item.

Show Value+Type
     Shows both the value and the type of the item.

Auto refresh
     Enables or disables the automatic refreshing of the item upon
     program execution (e.g step, next).

   A contextual menu can be accessed in the canvas itself (point the
mouse to    an empty area in the canvas, and click on the right mouse
button) with the    following entries:
Display Expression...
     Open a small dialog letting you specify an arbitrary expression
       in the Data Window. This expression can be a variable name, or a
          more complex expression, following the syntax of the current
     language and       underlying debugger.        See the
     documentation of e.g gdb for more details on the syntax.
     The check button Expression is a subprogram call should be enabled
          if the expression is actually not an expression but rather a
     debugger       command (e.g `p/x var') or a procedure call in the
     program being       debugged (e.g `call my_proc').

Align On Grid
     Enables or disables alignment of items on the grid.

Detect Aliases
     Enables or disables the automatic detection of shared data
     structures.  Each time you display an item or dereference a
     pointer, all the items already displayed on the canvas are
     considered and their addresses are compared with the address of
     the new item to display. If they match, (for example if you tried
     to dereference a pointer to an object already displayed) instead
     of creating a new item a link will be displayed.

Zoom in
     Redisplays the items in the data window with a bigger font

Zoom out
     Displays the items in the data window with smaller fonts and
     pixmaps. This can be used when you have several items in the
     window and you can't see all of them at the same time (for
     instance if you are displaying a tree and want to clearly see its
     structure).

Zoom
     Allows you to choose the zoom level directly from a menu.

Manipulating items
------------------

Moving items
............

All the items on the canvas have some common behavior and can be fully
manipulated with the mouse.  They can be moved freely anywhere on the
canvas, simply by clicking on them and then dragging the mouse. Note
that if you are trying to move an item outside of the visible area of
the data window, the latter will be scrolled so as to make the new
position visible.

   Automatic scrolling is also provided if you move the mouse while
dragging an item near the borders of the data window. As long as the
mouse remains close to the border and the button is pressed on the item,
the data window is scrolled and the item is moved. This provides an
easy way to move an item a long distance from its initial position.

Colors
......

Most of the items are displayed using several colors, each conveying a
special meaning. Here is the meaning assigned to all colors (note that
the exact color can be changed through the preferences dialog; these
are the default colors):

black
     This is the default color used to print the value of variables or
     expressions.

blue
     This color is used for C pointers (or Ada access values), i.e. all
     the variables and fields that are memory addresses that denote
     some other value in memory.

     You can easily dereference these (that is to say see the value
     pointed to) by double-clicking on the blue text itself.

red
     This color is used for variables and fields whose value has
     changed since the data window was last displayed. For instance, if
     you display an array in the data window and then select the Next
     button in the tool bar, then the elements of the array whose value
     has just changed will appear in red.

     As another example, if you choose to display the value of local
     variables in the data window (Display->Display Local Variables),
     then only the variables whose value has changed are highlighted,
     the others are left in black.

Icons
.....

Several different icons can be used in the display of items. They also
convey special meanings.

trash bin icon
     This icon indicates that the debugger could not get the value of
     the variable or expression. There might be several reasons, for
     instance the variable is currently not in scope (and thus does not
     exist), or it might have been optimized away by the compiler. In
     all cases, the display will be updated as soon as the variable
     becomes visible again.

package icon
     This icon indicates that part of a complex structure is currently
     hidden.  Manipulating huge items in the data window (for instance
     if the variable is an array of hundreds of complex elements) might
     not be very helpful. As a result, you can shrink part of the value
     to save some screen space and make it easier to visualize the
     interesting parts of these variables.

     Double-clicking on this icon will expand the hidden part, and
     clicking on any sub-rectangle in the display of the variable will
     hide that part and replace it with that icon.

     See also the description of the contextual menu to automatically
     show or hide all the contents of an item. Note also that one
     alternative to hiding subcomponents is to clone them in a separate
     item (see the contextual menu again).


File: gps.info,  Node: The Breakpoint Editor,  Next: The Memory Window,  Prev: The Data Window,  Up: Debugging

The Breakpoint Editor
=====================

The breakpoint editor can be accessed from the menu Data->Edit
Breakpoints. It gives access to the different kind of breakpoints: on
source location, subprogram, address, variables, exceptions.

   The top area provides an interface to easily create the different
kinds of breakpoints, while the bottom area lists the existing
breakpoints and their characteristics.

   It is possible to access to advanced breakpoint characteristics by
clicking on the Advanced button, which will display a new area on the
right of the window, where you can specify commands to run
automatically after a breakpoint is hit, or specify how many times a
selected breakpoint will be ignored.  If running VxWorks AE, you can
also change the Scope and Action of breakpoints.

Scope/Action Settings for VxWorks AE
------------------------------------

In VxWorks AE breakpoints have two extra properties:

   * Scope:  which task(s) can hit a given breakpoint. Possible Scope
     values are:
        - task:    the breakpoint can only be hit by the task that was
          active when the    breakpoint was set. If the breakpoint is
          set before the program is    run, the breakpoint will affect
          the environment task

        - pd:    any task in the current protection domain can hit that
          breakpoint

        - any:    any task in any protection domain can hit that
          breakpoint. This    setting is only allowed for tasks in the
          Kernel domain.


   * Action:  when a task hits a breakpoints, which tasks are stopped:
        - task:    stop only the task that hit the breakpoint.

        - pd:    stop all tasks in the current protection domain

        - all:    stop all breakable tasks in the system


   These two properties can be set/changed through the advanced
breakpoints characteristics by clicking on the Advanced button. There
are two ways of setting these properties:

   * Per breakpoint settings:  after setting a breakpoint (the default
     Scope/Action values will be  task/task), select the Scope/Action
     tab in the Advanced settings.   To change these settings on a
     given breakpoint, select it from  the breakpoints list, select the
     desired values of Scope and Action and click  on the Update button.

   * Default session settings:  select the Scope/Action tab in the
     Advanced settings. Select the desired Scope and Action settings,
     check  the Set as session defaults check box below and click the
     Close  button. From now on, every new breakpoint will have the
     selected values  for Scope and Action.



File: gps.info,  Node: The Memory Window,  Next: Using the Source Editor when Debugging,  Prev: The Breakpoint Editor,  Up: Debugging

The Memory Window
=================

The memory window allows you to display the contents of memory by
specifying either an address, or a variable name.

   To display memory contents, enter the address using the C
hexadecimal notation: 0xabcd, or the name of a variable, e.g foo, in
the Location text entry.  In the latter case, its address is computed
automatically. Then either press Enter or click on the View button.
This will display the memory with the corresponding addresses in the
bottom text area.

   You can also specify the unit size (Byte, Halfword or Word), the
format (Hexadecimal, Decimal, Octal or ASCII), and you can display the
corresponding ASCII value at the same time.

   The up and down arrows as well as the <Page up> and <Page down> keys
in the memory text area allows you to walk through the memory in order
of ascending/descending addresses respectively.

   Finally, you can modify a memory area by simply clicking on the
location you want to modify, and by entering the new values. Modified
values will appear in a different color (red by default) and will only
be taken into account (i.e written to the target) when you click on the
Submit changes button. Clicking on the Undo changes or going up/down in
the memory will undo your editing.

   Clicking on Close will close the memory window, canceling your last
pending changes, if any.

