Using the GNAT Programming System
*********************************

   Using the GNAT Programming System

   GPS, the GNAT Programming System

   Version 1.2.2

   Date: 2003/06/11 09:15:34

   Copyright (C) 2001-2003, ACT Europe.  This document may be copied,
in whole or in part, in any form or by any means, as is or with
alterations, provided that (1) alterations are clearly marked as
alterations and (2) this copyright notice is included unmodified in any
copy.

Introduction
************

GPS is a complete integrated development environment that gives access
to a wide range of tools and integrates them smoothly.

   GPS gives access to built-in file editing; HTML based help system;
complete compile/build/run cycle; intelligent source navigation;
project management; general graph technology giving access to many
different browsers such as source dependency, project dependency, call
graphs, etc...; fully integrated visual debugger, based on the GVD
technology, and enhanced for inclusion in GPS; generic version control
system, providing access to CVS, ClearCase, and possibly others in the
future; many other tools such as a visual comparison, automatic
generation of files, source reformatting.

   GPS is fully customizable, providing several levels of
customizations: a first level, available through the preferences dialog;
a second level, which allows you to customize your menu items, tool bar
and key bindings; a third level, which allows you to automate
processing through scripts; and a fourth level, which allows any kind
of very specific or tight integration, due to the open nature of GPS,
and to its architecture.  See *Note Customizing and Extending GPS:: for
more details.

   GPS also integrates with existing editors such as Emacs and Vi, see
*Note Using an External Editor::.

Description of the Main Windows
*******************************

The Welcome Dialog
==================

When starting GPS, a welcome dialog is displayed by default, giving the
following choices:

Start with default project in directory
     If you select this option and click on the `OK' button, GPS will
     create a default internal project with the following properties:

     The project supports Ada files only, using the default GNAT
     naming scheme: `.ads' for spec files, `.adb' for body files.

     A single source directory corresponding to the current directory.
      The current directory can be set by modifying the text entry on
     clicking   on the `Browse' button. All the Ada files found in this
     directory   will be considered as part of the default project.

     The object directory where the object and executable files will
     be put, corresponding also to the current directory.

Create new project with wizard
     Selecting this option and clicking on the `OK' button will start a
     wizard allowing you to specify most of the properties for a new
     project. Once the project is created, GPS will save it and load it
     automatically.  See *Note The Project Wizard:: for more details on
     the project wizard.

Open existing project
     You can select an existing project by clicking on the `Browse'
     button, or by using a previously loaded project listed in the
     combo box. When a project is selected, clicking on the `OK' button
     will load this project and open the main window.

Always show this dialog when GPS starts
     If unset, the welcome dialog won't be shown in future sessions.
     In this case, GPS will behave as follows: it will first look for a
     `-P' switch on the command line, and load the corresponding
     project if present.  Then, it will look for a project file in the
     current directory and will load the first project file found.

     If no project file can be found in the current directory, GPS will
     start with the default project.

     To reset this property, go to the menu `Edit->Preferences'.  *Note
     The Preferences Dialog::.

Quit
     If you click on this button, GPS will terminate immediately.

   When you specify a -P switch on the command line, or if there is
only one project file in the current directory, GPS will start
immediately with the project file specified, instead of displaying the
welcome dialog.

   In addition, if you specify source files on the command line, GPS
will also start immediately, using the default project if no project is
specified.

The Menu Bar
============

This is a standard menu bar that gives access to all the global
functionalities of GPS. It is usually easier to access a given
functionality using the various contextual menus provided throughout
GPS: these menus give direct access to the most relevant actions given
the current context (e.g. a project, a directory, a file, an entity,
...). Contextual menus pop up when the right mouse button is clicked.

   The menu bar gives access to the following items:

File
     *Note The File Menu::.

Edit
     *Note The Edit Menu::.

Navigate
     *Note The Navigate Menu::.

VCS
     *Note The VCS Menu::.

Project
     *Note The Project Menu::.

Build
     *Note The Build Menu::.

Debug
     *Note The Debug Menu::.

Tools
     *Note The Tools Menu::.

Window
     *Note Multiple Document Interface::.

Help
     *Note The Help Menu::.

The Tool Bar
============

The tool bar provides shortcuts via buttons to some typical actions:
creating a new file, opening a file, saving the current file; undo/redo
last editing; cut to clipboard, copy to clipboard, paste from clipboard;
go to previous/next location; start/continue the debugging session,
step/next execution, finish current procedure.

   The icon on the far right of the tool bar will be animated to
indicate that an action (e.g. a build or a search) is going on in
background.

The Work Space
==============

   The whole work space is based on a multiple document interface,
*Note Multiple Document Interface::.

The Project Explorer
====================

The project explorer is composed of multiple views which can be accessed
by default by clicking on the corresponding pages, or if they are not
shown by using the `Project' menu items.

The explorer views
------------------

The explorer views are initially displayed on the left side of the GPS
window. Their goal is to show a full view of the various components of
your projects. These various components are presented below.

   The following screen shot displays the two pages side-by-side: on the
left, the `Project View', and on the right the `File View'.

   Each view provides an interactive search capability allowing you to
quickly search in the information currently displayed. The default key
to start an interactive search is <Ctrl-i>. See *Note Interactive
Search:: for more details.

   The various components that are displayed in these explorers are the
following:

projects
     As mentioned before, all the sources you are working with are put
     under control of projects. These projects are a way to store the
     switches to use for the various tools, as well as a number of
     other properties.

     They can be organized into a project hierarchy, where a root
     project can import other projects, with their own set of sources.

     Initially, a default project is created, that includes all the
     sources in the current directory.

     The `Project View' page of the explorer displays this project
     hierarchy: the top node in this view is the root project of your
     application (generally, this is where the source file that contains
     the main subprogram will be located). Then a node is displayed for
     each imported project, and recursively for their own imported
     projects.

     A given project might appear multiple times in the `Project View',
     if it is imported by several other projects.

     There exists a second display for this project view, which lists
     all projects with no hierarchy: all projects appear only once in
     the explorer, at the top level. This display might be useful for
     deep project hierarchies, to make it easier to find projects in
     the explorer.

     This display is activated through the contextual menu entry `Show
     flat view', which acts as a switch between the two displays.

     A special icon with an exclamation mark is displayed if the project
     was modified, but not saved yet. You can choose to save it at any
     time by right-clicking on it. GPS will remind you to save it
     before any compilation.

directories
     The files inside a project can be organized into several physical
     directories on the disk. These directories are displayed under each
     project node in the `Project View', or directly mimicking their
     physical organization on the disk (including Windows drives) in the
     `File View'.

     In the `Project View', you can chose whether you want to see the
     absolute path names for the directories or paths relative to the
     location of the project. This is done through the `Show absolute
     paths' contextual menu.

     Special nodes are created for object and executables directories.
     No files are shown for these.

files
     The source files themselves are stored in the directories, and
     displayed under the corresponding nodes. Note that in the `Project
     View', only the source files that actually belong to the project
     (i.e. are written in a language supported by that project and
     follow its naming scheme) are actually visible.

     The `File View' will display all the files that actually exist on
     the disk. Filters can be set through the contextual menu to only
     show the files and directories that belong to the project
     hierarchy. See the menu `Show files from project only'.

     A given file might appear multiple times in the `Project View', if
     the project it belongs to is imported by several other projects.

entities
     If you open the node for a source file, the file is parsed by one
     of the fast parsers integrated in GPS so that all entities
     declared in the project can be shown. These entities are grouped
     into various categories, which depend on the language. Typical
     categories include subprograms, packages, types, variables,
     tasks,...

   Double-clicking on an file, or simple clicking on any entity will
open a source editor and display respectively the first line in this
file or the line on which the entity is defined.

   If you open the search dialog through the `Navigate->Find...' menu,
you have the possibility to search for anything in the explorer, either
a file or an entity. Note that searching for an entity might be a
little slow if you have lots of files.

   A contextual menu, named `Locate in Explorer', is also provided when
inside a source editor. This will automatically search for the first
entry for this file in the explorer. This contextual menu is also
available in other modules, e.g. when selecting a file in the
`Dependency Browser'.

The configuration variables
---------------------------

As described in the GNAT User's Guide, the project files can be
configured through external variables (typically environment
variables). This means that e.g. the exact list of source files, or the
exact switches to use to compile the application can be changed when
the value of these external variables is changed.

   GPS provides a simple access to these variables, through a special
area on top of the `Project View'. These variables are called
`Configuration Variables', since they provide various scenarios for the
same set of project files.

   A combo box is displayed in this area for each environment variable
the project depends on. The current value of the variable can be set
simply by selecting it from the pop-down window that appears when you
click on the arrow on the right of the variable name

   New variables can be added through the contextual menu `Add
Configuration Variable' in the `Project View'. The list of possible
values for a variable can be changed by clicking on the button on the
left of the variable's name.

   Whenever you change the value of one of the variables, the project is
automatically recomputed, and the list of source files or directories
is changed dynamically to reflect the new status of the project.
Starting a new compilation at that point will use the new switches, and
all the aspects of GPS are immediately affected according to the new
setup.

The Messages Window
===================

The Messages window is used by GPS to display information and feedback
about operations, such as build output, information about processes
launched, error messages.

   This is a read-only window, which means that only output is
available, no input is possible.

   For an input/output window, see *Note The Execution Window:: and also
*Note The Shell Window::

The Shell Window
================

These windows give access to the various scripting languages supported
by GPS, and allow you to type commands such as editing a file or
compiling without using the menu items or the mouse.

   See *Note Scripting GPS:: for more information on using scripting
languages within GPS.

   You can use the <up> and <down> keys to navigate through the history
of commands.

The Locations Tree
==================

The Location Tree is filled whenever GPS needs to display a list of
locations in the source files (typically, when performing a global
search, compilation results, and so on).

   The Location Tree shows a hierarchy of categories, which contain
files, which contain locations. Clicking on a location item will bring
up a file editor at the requested place. Right-clicking on file or
category items brings up a contextual menu allowing you to remove the
corresponding node from the view.

   To navigate through the next and previous location (also called
`Tag'), you can use the menu items `Navigate->Previous Tag' and
`Navigate->Next Tag', or the corresponding key bindings.

   In some cases, a wrench icon will be associated on the left of a
compilation message. See *Note Code Fixing:: for more information on
how to make advantage of this icon.

The Execution Window
====================

Each time a program is launched using the menu `Build->Run', a new
execution window is created to provide input and output for this
program.

   In order to allow post mortem analysis and copy/pasting, the
execution windows are not destroyed when the application terminates.

   To close an execution window, click on the cross icon on the top
right corner of the window, or use the menu `File->Close', or the menu
`Window->Close' or the key binding <Ctrl-W>.

   If you close the execution window while the application is still
running, a dialog window is displayed, asking whether you want to kill
the application, or to cancel the close operation.

The Status Line
===============

The status line is composed of two areas: on the left a status bar and
on the right a progress bar.

   The status bar is used to display temporary information about GPS
operations. Note that most of the information GPS displays can be found
in the `Messages' window.

   The progress bar is used to display information about on going
operations such as builds.

Integrated Help
***************

By default when you start GPS, the working area contains a help window
displaying HTML help files. On-line help for the GNAT tools is available
from the `Help' menu item.

   Since HTML pages can contain lots of complex information, resizing
the help window can take some time, making the user interface less
responsive.  It is therefore recommended to close the `Help' window
when not using it. You can reopen this window at any time using the
`Help' menu item.

   For the best use of the integrated help, it is recommended to load
small HTML pages each time instead of long pages which will be slow to
load and display.

The Help Menu
=============

The Help menu item provides the following entries:

Contents
     This opens a special HTML file that contains links for all the
     documentation files currently registered in GPS, *Note Adding New
     Help Files::.

Zoom in
     Increase the size of the font used to display the help file.

Zoom out
     Decrease the size of the font used to display the help file.

Open HTML file...
     Open a file selection dialog to load an HTML file.

About
     Display a dialog giving information about the versions of GPS and
     GNAT used:

   This menu contains a number of additional entries, depending on what
documentation packages were installed on your system. See the next
section to see how to add new help files.

   The help window also provides a contextual menu that gives the
possibility to copy the current selection to the clipboard.

Adding New Help Files
=====================

GPS will search for the help files in the list of directories set in
the environment variable `GPS_DOC_PATH' (a colon-separated list of
directories on Unix systems, or semicolon-separated list of directories
on Windows systems). If this variable is not set, the default directory
`<prefix>/doc/gps/html' is searched.  If the file cannot be found in
any of these directories, the corresponding menu item will be disabled.

   The environment variable `GPS_DOC_PATH' can either be set by each
user in his own environment, or can be set system-wide by modifying the
small wrapper script `gps' itself on Unix systems.

   The specific list of files shown in the menus is set by reading the
index files in each of the directories in `GPS_DOC_PATH'. These index
files must be called `gps_index.xml', and their format can be see in
the following example:

     <?xml version="1.0"?>
     <index>
        <file>
           <name>file.html</name>
           <descr>Tooltip text</descr>
           <category>name</category>
           <menu>/Help/item</menu>
        </file>
     </index>

   There should be one `<file>' tag per help file. This tag contains
four children tags:

name
     This is the name of the file. It can be either an absolute file
     name, or a file name relative to one of the directories in
     `GPS_DOC_PATH'.

     This name can contain a reference to a specific anchor in the html
     file, using the standard HTML syntax.

            <name>file#anchor</name>

descr
     This is the description for this help file. It appears in a tool
     tip for the menu item.

category
     This is used in the `Help->Contents' menu to organize all the
     documentation files.

menu
     This is the full path to the menu. It behaves like a UNIX path,
     except it reference the various menus, starting from the menu bar
     itself. The first character of this path must be `"/"'. The last
     part of the path is the name of the new menu item. If not set, no
     menu is displayed for this file, although it will still appear in
     the `Help->Contents' menu

Multiple Document Interface
***************************

All the windows that are part of the GPS environment are under control
of what is commonly called a multiple document interface (MDI for
short). This is a common paradigm on windowing systems, where related
windows are put into a bigger window which is itself under control of
the system or the windows manager.

   This means that, by default, no matter how many editors, browsers,
explorers,... windows you have opened, your system will still see only
one window (On Windows systems, the task bar shows only one icon).
However, you can organize the GPS windows exactly the way you want, all
inside the GPS main window.

   For instance, you can choose to iconify some windows which are
temporarily useless to you; you can choose to put some windows on top
of others; you can resize all the windows to the size you want; and so
on.

   This section will show the various capacities that GPS provides to
help you organize your workspace.

Selecting Windows
=================

At any time, there is only one selected window in GPS (the active
window). You can select a window either by clicking in its title bar,
which will then get a different color, or by selecting its name in the
menu `Window'.

   Alternatively, windows can be selected with the keyboard. By default,
the selection key is <Alt-Tab>. When you press it, a temporary dialog
is popped-up on the screen, with the name of the window that will be
selected when the key is released. If you press the selection key
multiple times, this will iterate over all the windows currently open
in GPS.

   This interactive selection dialog is associated with a filter,
displayed below the name of the selected window. If you maintain <Alt>
pressed while pressing other keys than <Tab>, this will modify the
current filter. From then on, pressing <Alt-Tab> will only iterate
through those windows that match the filter.

   The filter is matched by any window whose name contains the letter
you have typed. For instance, if you are currently editing the files
`unit1.adb' and `file.adb', pressing <t> will only leave `unit1.adb'
selectable.

Closing Windows
===============

Wherever the windows are displayed, they are always closed in the same
manner. In the right side of the title bar of the window, three small
buttons are displayed. The rightmost button is a cross. Clicking on
this button will close the window.

   When a window is closed, the focus is given to the window of the same
part of the MDI (each of the docks or the middle area) that previously
had the focus. Therefore, if you simply open an editor as a result of a
cross-reference query, you can simply close that editor to go back to
where you were before.

   Alternatively, you can also select the window by clicking anywhere in
its title bar, and then select the menu `Window->Close'

Maximized and Iconified Windows
===============================

The MDI is initially split into three parts: one window to the left,
one to the bottom, and a bigger one that occupies the remaining space.

   The first two will be discussed in *Note Docked Windows::.  The
third area is the one that provides the most flexibility:

maximized windows
     The windows in this area are initially maximized. This means that
     if you have several windows, a notebook will be created, and only
     one window will be visible at any given time. You select the
     window you want to see by clicking on the appropriate tab.

     Note that if there are a lot of windows, two small arrows will
     appear on the right of the tabs. Clicking on these arrows will
     show the remaining tabs.

     You can go back to this maximized state in two ways: either select
     the menu `Window->Maximize All', or click on the middle button on
     the right of the title bar of any window (this button shows two
     small squares, and will toggle between maximized and unmaximized
     states.

unmaximized windows
     As opposed to putting all the windows inside a notebook, GPS can
     also let you organize them freely when they are unmaximized.
     Select the menu `Window->Unmaximize All', or click again in the
     middle button on the right of the title bar.

     In this mode, the windows can be resized freely by clicking on the
     border of any side or in one of their four corners, as usual on
     windowing systems.

     They can also be moved around. As a result, you can choose for
     instance to display several windows side by side, or one on top of
     the others.

     To make it easier to get to these standard organizations, GPS
     provides a few shortcuts through menus:

    `Window->Cascade'
          All the windows will be resized to the same size, and be
          moved one on top of the other, so that the top and left sides
          of all windows are visible. This way, you can easily select
          any window

    `Window->Tile Horizontally'
          All the windows are resized to the same dimensions, and are
          put side by side, from left to right. No window will overlap
          any other.

    `Window->Tile Vertically'
          All the windows are resized to the same dimensions, and are
          put side by side, from top to bottom. No window will overlap
          any other.

Iconified windows
     When the windows are unmaximized, you can also choose to
     temporarily iconify some of them. This is done by clicking on the
     leftmost button in the title bar (the one that shows a single
     line).

     The window will then be resized so that only part of its title bar
     is visible, and none of its actual contents. Icons can still be
     moved around as you want, but they can not be resized. You need to
     first de-iconify the window, by clicking once again on the same
     button.

     When de-iconified, a window will restore the size and position it
     had before it was iconified.

Docked Windows
==============

As mentioned before, the GPS work space is initially split into three
windows. The one on the left and the one at the bottom are called
docking area.

   They have a different behavior from the central area, since windows
in these areas are necessarily grouped into a notebook. Thus, only one
of them is visible at any given time, and you select the one you want to
see by clicking on its name in the tabs area.

   GPS includes four such areas, one on each side of the main area. Some
visual objects will initially be displayed in one of these docking areas
instead of in the central one, like the project explorer, the message
window,... Although you can not control this initial position, it is
possible to change it later on (*Note Moving Windows::).

   However, you can still choose precisely the dimension you want for
this docking area (either its width for the left and right areas, or
its height for the top and bottom ones).

   Between each docking area and the central one, there is a small
handle (on which a series of dots are drawn), that you can move
interactively with the mouse, to resize the docking areas). By default,
when you move such a handle, a line will appear on top of all other
windows in GPS to show you the new position the docking area will have
when you release the mouse. You can set up a preference (menu
`Edit->Preferences') to indicate that you want the resizing to be
opaque, which might give more intuitive results.

   Note that when a window is docked (i.e. put in a docking area), some
of the buttons in its title bar are grayed out and inactive.

   A simple way to dock a window is to select it, and then select the
menu `Window->Docked'. We will see in *Note Moving Windows:: that there
is a more intuitive way to do the same thing.

   In some cases, GPS will change the color used to draw the title of
the window in the notebook tab. This indicates that the window content
has been updated, but the window wasn't visible. Typically, this is
used to indicate that new messages have been written in the messages or
console window.

Floating Windows
================

Although the MDI, as described so far, is already extremely flexible,
it is possible that you prefer to have several top-level windows under
direct control of your system or window manager. This would be the case
for instance if you want to benefit from some extra possibilities that
your system might provide (virtual desktops, different window
decoration depending on the window's type, transparent windows,...).

   GPS is fully compatible with this behavior, since windows can also be
floating windows. Any window that is currently embedded in the MDI can
be made floating at any time, simply by selecting the window and then
selecting the menu `Window->Floating'. The window will then be
detached, and can be moved anywhere on your screen, even outside of
GPS's main window.

   There are two ways to put a floating window back under control of
GPS.  The more general method is to select the window through its title
in the menu `Window', and then select `Window->Floating'.

   The second method assumes that the preference Destroy Floats in the
menu `Edit->Preferences' has been set to false. Then, you can simply
close the floating window by clicking in the appropriate title bar
button, and the window will be put back in GPS. If you actually want to
close it, you need to click once again on the cross button in its title
bar.

   A special mode is also available in GPS, where all windows are
floating. The MDI area in the main window becomes invisible. This can
be useful if your system or window manager provides windows-handling
facilities that GPS does and you rely on them. It might also be used if
you want to have windows on various virtual desktops, when your window
manager has this feature.

   This special mode is activated through a preference (menu
`Edit->Preferences'). This preference is entitled All Floating.

Moving Windows
==============

As we have seen, the windows' state can be changed at any time, from
maximized to unmaximized to docked and floating and back, in any order.

   In all cases, the changes are done either through the buttons in the
title bar or through the menu `Window'.

   On some systems, a more intuitive method is also provided, based on
the drag-and-drop paradigm. The idea is simply to select a window,
wherever it is, and then, by clicking on it and moving the mouse while
keeping the left button pressed, drop it anywhere else inside GPS.

   Selecting an item so that it can be dragged is done simply by
clicking with the left mouse button in its title bar, and keep the
button pressed while moving the mouse. Although this is the general
scheme, this would work for unmaximized items, since the title bar is
then used to move them around. In that case, you need to press the
<control> key in addition to the left mouse button.

   A third possibility can be used for maximized or docked windows:
click with the left mouse button in the notebook tab that contains their
name. This third option is not available under Windows systems.

   It is important to note that some visual objects in GPS have their
own drag-and-drop support, and will not react when you drop a window on
them. For instance, editors use drag-and-drop for copy-paste
operations. Therefore, dropping a window on them will result in a
failed operation. In that case, it always works to drop the window in
the title bar of another window to adopt the same state.

   Here are the various places where a window can be dropped:

The central area
     The window you are dropping will get the same state as the other
     windows already in this area (maximized or unmaximized).

Docking areas
     The window will immediately be adopted by this dropping area, and a
     new notebook will be created as needed. Once again, since the
     message window has its own handling of drag-and-drop, you can not
     drop items on it. Instead, drop windows on its title bar.

     In some cases, you might want to create a docking area that is not
     currently visible (for instance, it is often useful to put an
     editor in the right docking area, so that two editors can be seen
     side-by-side, one in this area, and one in the central one).

     To achieve this, drop the window on the small handle that surrounds
     the whole GPS window (a black rectangle will appear on the screen
     when your mouse is over that area). If you then drop the item, a
     new docking area will be created.

System window
     Under systems that support it, if you drop a window outside of GPS
     (for instance, on the background of your screen), the window will
     be floated.

Sides of the GPS window
     On each side of the GPS window, a small zone (a few pixels high or
     wide) is set up as a drop-area. If you drop a window on these zone
     (they are briefly highlighted while the mouse stays on them), then
     the window will be added to the dock on that side. If there is no
     dock area on that side, one will be created.

     This is especially useful if you want to put two editor windows
     side by side. Drag one of them on the drop area on the right side.

Editing Files
*************

General Information
===================

Source editing is one of the central parts of GPS, giving in turn access
to many other functionalities, including extended source navigation and
source analyzing tools.

   The integrated source editor provides all the usual capabilities
found in integrated environments, including:

A title bar
     Showing the full name of the file including path information.

Line number information
     This is the left area of the source editor. Line numbers can be
     disabled from the preferences. *Note The Preferences Dialog::.
     Note that this area can also display additional information, such
     as the current line of execution when debugging, or cvs
     annotations.

A scrollbar
     Located on the right of the editor, it allows you to scroll
     through the source file.

A status bar
     Giving information about the file.  If the file is maintained
     under version control, and version control is supported and
     enabled in GPS, the first box on the left will show VCS
     information on the file: the VCS kind (e.g. CVS), followed by the
     revision number, and if available, the status of the file.

     The second box shows the writable state of the file.  You can
     change this state by clicking on the label directly: this will
     switch between writable and read-only.  Note that this will not
     change the permissions of the file on disk, it will only change
     the writable state of the source editor within GPS.

     When trying to save a file which is read only on the disk, GPS
     will ask for confirmation, and if possible, will force saving of
     the file, keeping its read only state.

     The third box shows whether the file has been modified since the
     last save. The three possible states are:

    Unmodified
          The file has not been modified since the file has been loaded
          or saved.

    Modified
          The file has been modified since last load or save. Note that
          if you undo all the editing operations until the last save
          operation, this label will change to Unmodified.

    Saved
          The file has been saved and not modified since.

     The fourth box displays the position of the cursor in the file by
     a line and a column number.

A contextual menu
     Displayed when you right-click on any area of the source editor.
     See in particular *Note Source Navigation Contextual Menus:: for
     more details.

Syntax highlighting
     Based on the programming language associated with the file,
     reserved words and languages constructs such as comments and
     strings are highlighted in different colors and fonts. See *Note
     The Preferences Dialog:: for a list of settings that can be
     customized.

Automatic indentation
     When enabled, lines are automatically indented each time you press
     the <Enter> key, or by pressing the indentation key.  The
     indentation key is <Ctrl-Tab> by default, and can be changed in the
     preferences dialog, *Note The Preferences Dialog::.

     If a set of lines is selected when you press the indentation key,
     this whole set of lines will be indented.

Tooltips
     When you leave the mouse over a word in the source editor, a small
     window will automatically pop up if there are relevant contextual
     information to display about the word.

     The kind of information displayed depends on the current state of
     GPS.

     In normal mode, the kind of entity and where it is declared is
     displayed when this information is available. That is, when the
     cross reference information about the current file has been
     generated. If there is no relevant information, no tooltip is
     displayed.  See *Note Support for Cross References:: for more
     information.

     In debugging mode, the value of the variable under the mouse is
     displayed in the pop up window if the variable is known to the
     debugger, in the right frame, and if the program being debugged is
     in the right state. If one of these conditions is not met, the
     normal mode information is displayed.

     You can disable the automatic pop up of tool tips in the Editor
     section of the preferences dialog. *Note The Preferences Dialog::.

Word completion
     It is useful when editing a file and using often the same words to
     get automatic word completion. This is possible by typing the
     <Ctrl-/> key combination (customizable through the preferences
     dialog) after a partial word: the next possible completion will be
     inserted in the editor. Typing this key again will cycle through
     the list of possible completions.

     Completions are searched in the edited source file, by first
     looking at the closest words and then looking further in the
     source as needed.

Delimiter highlighting
     When the cursor is moved before an opening delimiter or after a
     closing delimiter, then both delimiters will be highlighted. The
     following characters are considered delimiters: ()[]{}.  You can
     disable highlighting of delimiters in the preferences.

     You can also jump to a corresponding delimiter by using the
     <Ctrl-'> key, that can be configured in the preferences. Typing
     twice on this key will move the cursor back to its original
     position.

Current line highlighting
     You can configure the editor to highlight the current line with a
     certain color. *Note The Preferences Dialog::.

Auto save
     You can configure the editor to periodically save modified files.
     See *Note autosave delay:: for a full description of this
     capability.

   GPS also integrates with existing third party editors such as
`Emacs'. *Note Using an External Editor::.

Editing Sources
===============

Key bindings
------------

In addition to the standard keys used to navigate in the editor (up,
down, right, left, page up, page down), the integrated editor provides
a number of key bindings allowing easy navigation in the file.

   The key bindings are listed below in two sections: the common key
bindings, always available; the Emacs key bindings, available as an
option.

   In addition, there are several ways to define new key bindings, see
*Note Defining Text Aliases:: and *Note Defining new key bindings::.

Common key bindings

    <Ctrl-Shift->
          Pressing these two keys allow you to enter characters using
          their hexadecimal value. For example, pressing
          <Ctrl-Shift-2-0> will insert a space character (ASCII 32,
          which is 20 in hexadecimal).

    <Ctrl-x / Shift-delete>
          Cut to clipboard

    <Ctrl-c / Ctrl-insert>
          Copy to clipboard

    <Ctrl-v / Shift-insert>
          Paste from clipboard

    <Ctrl-s>
          Save file to disk

    <Ctrl-z>
          Undo previous insertion/deletion

    <Ctrl-r>
          Redo previous insertion/deletion

    <Insert>
          Toggle overwrite mode

    <Ctrl-a>
          Select the whole file

    <Home / Ctrl-Pgup>
          Go to the beginning of the line

    <End / Ctrl-Pgdown>
          Go to the end of the line

    <Ctrl-Home>
          Go to the beginning of the file

    <Ctrl-End>
          Go to the end of the file

    <Ctrl-up>
          Go to the beginning of the line, or to the previous line if
          already at the beginning of the line.

    <Ctrl-down>
          Go to the end of the line, or to the beginning of the next
          line if already at the end of the line.

    <Ctrl-delete>
          Delete end of the current word.

    <Ctrl-backspace>
          Delete beginning of the current word.

Emacs key bindings
     The following key bindings are activated if you select the Emacs
     key theme in the preferences dialog (*Note The Preferences
     Dialog::.), and may override common keys (e.g. <Ctrl-a>).

    <Ctrl-b>
          Move the cursor one character on the left

    <Shift-Alt-b>
          Select the previous word (backward).

    <Shift-Alt-f>
          Select the next word (forward).

    <Ctrl-a>
          Go to the beginning of the line

    <Ctrl-e>
          Go to the end of the line

    <Ctrl-d>
          Delete the next character

    <Ctrl-k>
          Delete the end of the line. If the cursor is already at the
          end of the line, remove the line separator.

    <Alt-\>
          Delete all space characters around the cursor.

    <Alt-space>
          Replace all space characters around the cursor by a single
          space.

    <Alt-<>
          Go to the beginning of the file

    <Alt->>
          Go to the end of the file

    <Shift-Ctrl-p>
          Select from cursor to one line up.

    <Shift-Ctrl-n>
          Select from cursor to one line down.

    <Ctrl-j>
          Join the current and the next lines and leave a single space
          between the two. This is similar to the <J> key in the vi
          editor.  This is a useful extension compared to the default
          Emacs key bindings.

The File Selector
=================

The file selector is a dialog used to select a file. Under Windows, the
default is to use the standard file selection widget. Under other
platforms, the file selector is a built-in dialog:

This dialog provides the following areas and capabilities:

   * A tool bar on the top composed of five buttons giving access to
     common navigation features:

    left arrow
          go back in the list of directories visited

    right arrow
          go forward

    up arrow
          go to parent directory

    refresh
          refresh the contents of the directory

    home
          go to home directory (value of the HOME environment variable,
          or `/' if   not defined)

   * A list with the current directory and the last directories
     explored.  You can modify the current directory by modifying the
     text entry and hitting <Enter>, or by clicking on the right arrow
     and choose a previous directory in the pop down list displayed.

   * A directory tree. You can open or close directories by clicking on
     the `+' and `-' icons on the left of the directories, or navigate
     using the keyboard keys: <up> and <down> to select the previous or
     the next directory, <+> and <-> to expand and collapse the current
     directory, and <backspace> to select the parent directory.

   * A file list. This area lists the files contained in the selected
     directory. If a filter is selected in the filter area, only the
     relevant files for the given filter are displayed. Depending on
     the context, the list of files may include additional information
     about the files, e.g. the kind of a file, its size, etc...

   * A filter area. Depending on the context, one or several filters are
     available to select only a subset of files to display. The filter
     All files which is always available will display all files in the
     directory selected.

   * A file name area. This area will display the name of the current
     file selected, if any.  You can also type a file or directory name
     directly, and complete the name automatically by using the <Tab>
     key.

   * A button bar with the `OK' and `Cancel' buttons.  When you have
     selected the right file, clock on `OK' to confirm, or click on
     `Cancel' at any time to cancel and close the file selection.


Menu Items
==========

The main menus that give access to extended functionalities related to
source editing are described in this section.

The File Menu
-------------

New
     Open a new untitled source editor.  No syntax highlighting is
     performed until the file is saved, since GPS needs to know the
     file name in order to choose the programming language associated
     with a file.

     When you save a new file for the first time, GPS will ask you to
     enter the name of the file. In case you have started typing Ada
     code, GPS will try to guess based on the first main entity in the
     editor and on the current naming scheme, what should be the
     default name of this new file.

New View
     Create a new view of the current editor. The new view shares the
     same contents: if you modify one of the source views, the other
     view is updated at the same time. This is particularly useful when
     you want to display two separate parts of the same file, for
     example a function spec and its body.

Open...
     Open a file selection dialog where you can select a file to edit.
     Under Windows, this is the standard file selector. Under other
     platforms, this is a built-in file selector described in *Note The
     File Selector::.

Open From Project...
     Open a dialog where you can easily and rapidly select a source
     file from your project.

     The first text area allows you to type a file name. You can start
     the beginning of a file name, and use the <Tab> key to complete
     the file name. If there are several possible completions, the
     common prefix will be displayed, and a list of all possible
     completions will be displayed in the second text area.

     You can then either complete the name by typing it, or continue
     hitting the <Tab> key to cycle through the possible completions,
     or click on one of the completions in the list displayed.

     You can also directly access the previous file names typed in this
     dialog by clicking on the down arrow on the right of the first
     text area.

     Once you have made your choice, click on the `OK' button to
     validate.  Clicking on `Cancel' or hitting the <Esc> key will
     cancel the operation and close the dialog.

Recent
     Open a sub menu containing a list of the ten most recent files
     opened in GPS, so that you can reopen them easily.

Save
     Save the current source editor if needed.

Save As...
     Same current file under a different name, using the file selector
     dialog.  *Note The File Selector::.

Save...
     Give access to extra save capabilities.

    All
          Save all items, including projects, etc...

    Desktop
          Save the desktop to a file. The desktop includes information
          about files, graphs, ... and their window size and position
          in GPS. The desktop is saved per top level project.

    Default Desktop
          Save the current desktop as the default desktop. The next
          time you start GPS, if there is no saved desktop associated
          with the chosen project, then this desktop will be used.

Change Directory...
     Open a directory selection dialog that lets you change the current
     working directory.

Messages
     This sub menu gives access to functionalities related to the
     Messages window.  *Note The Messages Window::.

    Clear
          Clear the contents of the Messages window.

    Save As...
          Save the contents of the Messages window to a file. A file
          selector is displayed to choose the name and location of the
          file.

    Load Contents...
          Open a file selector to load the contents of a file in the
          Messages window. Source locations are identified and loaded
          in the Locations Tree.  *Note The Locations Tree::.

Close
     Close the current window. This applies to all GPS windows, not
     only source editors.

Print
     Print the current file by first saving it interactively if needed
     (if it has been modified), and then by launching the command
     defined in the preferences.  *Note Print Command::.

Exit
     Exit GPS after confirmation and if needed, confirmation about
     saving modified windows and editors.

The Edit Menu
-------------

Undo
     Undo previous insertion/deletion in the current editor.

Redo
     Redo previous insertion/deletion in the current editor.

Cut
     Cut the current selection and store it in the clipboard.

Copy
     Copy the current selection to the clipboard.

Paste
     Paste the contents of the clipboard to the current cursor position.

Select All
     Select the whole contents of the current source editor.

Comment Lines
     Comment the current selection or line based on the current
     programming language syntax.

Uncomment Lines
     Remove the comment delimiters from the current selection or line.

Generate Body
     Generate Ada body stub for the current source editor by calling the
     external tool `gnatstub'.

Pretty Print
     Pretty print the current source editor by calling the external tool
     `gnatpp'. It is possible to specify `gnatpp' switches in the
     switch editor. *Note The Switches Editor::.

Unit Testing
     This sub menu gives access to dialogs that make it easy to generate
     AUnit stubs. AUnit is an Ada unit testing frame work.

    New Test Case...
          Create a new test case. See AUnit documentation for more
          details.

    New Test Suite...
          Create a new test suite. See AUnit documentation for more
          details.

    New Test Harness...
          Create a new harness. See AUnit documentation for more
          details.

Preferences
     Give access to the preferences dialog. *Note The Preferences
     Dialog::.

Using an External Editor
========================

GPS is fully integrated with a number of external editors, in
particular `Emacs' and `vi'. The choice of the default external editor
is done in the preferences. *Note The Preferences Dialog::.  The
following values are recognized:

`gnuclient'
     This is the recommended client. It is based on Emacs, but needs an
     extra package to be installed. This is the only client that
     provides a full integration in GPS, since any extended lisp
     command can be sent to the Emacs server.

     By default, gnuclient will open a new Emacs frame for every file
     that is opened. You might want to add the following code to your
     `.emacs' file (create one if needed) so that the same Emacs frame
     is reused every time:

             (setq gnuserv-frame (car (frame-list)))

     See <http://www.hpl.hp.co.uk/people/ange/gnuserv/> for more
     information.

`emacsclient'
     This is a program that is always available if you have installed
     Emacs. As opposed to starting a new Emacs every time, it will
     reuse an existing Emacs session. It is then extremely fast to open
     a file.

`emacs'
     This client will start a new Emacs session every time a file needs
     to be opened. You should use `emacsclient' instead, since it is
     much faster, and makes it easier to copy and paste between multiple
     files. Basically, the only reason to use this external editor is if
     your system doesn't support `emacsclient'.

`vim'
     `Vim' is a vi-like editor that provides a number of enhancements,
     for instance syntax highlighting for all the languages supported by
     GPS. Selecting this external editor will start an xterm (or command
     window, depending on your system) with a running vim process
     editing the file.

     Note that one limitation of this editor is that if GPS needs to
     open the same file a second time, it will open a new editor,
     instead of reusing the existing one.

     To enable this capability, the xterm executable must found in the
     PATH, and thus is not currently supported on Windows systems.

`vi'
     This editor works exactly like vim, but uses the standard `vi'
     command instead of `vim'.

`custom'
     You can specify any external editor by choosing this item. The full
     command line used to call the editor can be specified in the
     preferences (see *Note custom editor command::).

`none'
     No external editor is used, and the contextual menus simply won't
     appear.

   In the cases that require an Emacs server, GPS will try several
solutions if no already running server was found. It will first try to
spawn the glide environment distributed with GNAT. If not found in the
PATH, it will then start a standard Emacs. The project file currently
used in GPS will be set appropriately the first time Emacs is spawned.
This means that if you load a new project in GPS, or modify the paths
of the current project, you should kill any running Emacs, so that a
new one is spawned by GPS with the appropriate project.

   Alternatively, you can reload explicitly the project from Emacs
itself by using the menu `Project->Load'

   In the preferences, there are three settings that allow you to select
the external editor (if left to an empty string, GPS will automatically
select the first editor available on your system), to specify the
custom editor command, in case you've selector this item, and whether
this editor should always be used every time you double-click on a
file, or whether you need to explicitly select the contextual menu to
open the external editor.

Using the Clipboard
===================

This section concerns X-Window users who are used to cutting and
pasting with the middle mouse button. In the GPS text editor, as in
many recent X applications, the GPS clipboard is set by explicit
cut/copy/paste actions, either through menu items or keyboard
shortcuts, and the primary clipboard (i.e. the "middle button"
clipboard) is set by the current selection.

   Therefore, copy/paste between GPS and other X applications using the
primary clipboard will still work, provided that there is some text
currently selected. The GPS clipboard, when set, will override the
primary clipboard.

   See <http://www.freedesktop.org/standards/clipboards.txt> for more
information.

Source Navigation
*****************

Support for Cross References
============================

GPS provides cross-references for most of the entities defined in your
application, as well as some advanced browsers like a call graph.  For
this to work, it needs some help from external tools, specific to each
of the supported languages.

Ada
     The GNAT compiler itself is used to generate the cross-references
     information. This means that you need to compile your application
     to get access to this feature or the various graphs.  If your
     sources have been modified, you should recompile the modified
     files.

     If you need to navigate through sources that are not fully
     compilable (e.g after heavy modifications, or while porting an
     application), GNAT can still generate partial information if you
     specify the `-gnatQ' compilation option. Along with the `-k'
     option of gnatmake, it is then possible to generate as much
     relevant information as possible for a complete set of non
     compilable sources.

     There are a few special cases where GPS can not find the external
     file (called `ALI file') that contains the cross-reference
     information. Most likely, this is either because you haven't
     compiled your sources yet, or because the source code has changed
     since the `ALI file' was generated.

     It could also be that you haven't included in the project the
     object directories that contain the `ALI files'.

     In addition, one special case can not be handled automatically.
     This is for separate units, whose file names have been crunched
     through the `gnatkr' command. To handle this, you should force GPS
     to parse all the `ALI files' in the appropriate object directory.
     This is done by right-clicking on the object directory in the
     explorer (left-side panel on the main window), and selecting the
     menu "Parse all xref information".

C/C++
     To enable the navigation features for C and C++ source files, you
     need to first generate a database of symbol references, by going
     through the menu Build->Recompute C/C++ Xref info. Messages in the
     console window will indicate the state of the processing. Due to
     the nature of these languages, in order to provide accurate cross
     references, GPS needs to generate the database in two phases: a
     first pass parses all the files that have been modified since the
     previous parsing, and a second pass generates global cross
     references by analyzing the complete database.  It is thus
     expected that for large projects, this phase can take a
     significant amount of CPU to proceed.

     In some cases, GPS won't be able to determine the exact function
     involved in a cross reference. This will typically occur for
     overloaded functions, or if multiple functions with the same name,
     but under different `#ifdef' sections, are defined. In this case,
     GPS will display a dialog listing the possible choices to resolve
     the ambiguity.

     In addition, the C/C++ parser has the following limitations: name
     spaces are currently ignored (no specific processing is done for
     name spaces); no attempt is made to process the macros and other
     preprocessor defines.  Macros are considered as special entities,
     so it is possible to navigate from a macro use to its definition,
     but the macro content is ignored, which means for example that
     function calls made through macros won't be detected.

The Navigate Menu
=================

Find/Replace...
     Open the find and replace dialog. *Note Searching and Replacing::.

Find Next
     Find next occurrence of the current search. *Note Searching and
     Replacing::.

Find Previous
     Find previous occurrence of the current search.  *Note Searching
     and Replacing::.

Goto Declaration
     Go to the declaration/spec of the current entity. The current
     entity is determined by the word located around the cursor.  This
     item is also accessible through the editor's contextual menu
     directly.  This capability requires support for cross references.

Goto Body
     Go to the body/implementation of the current entity.  This item is
     also accessible through the editor's contextual menu directly.
     This capability requires support for cross references.

Goto Line...
     Open a dialog where you can type a line number,  in order to jump
     to a specific location in the current source editor.

Goto File Spec<->Body
     Open the corresponding spec file if the current edited file is a
     body file, or body file otherwise. This option is only available
     for the Ada language.  This item is also accessible through the
     editor's contextual menu

Find All References
     Find all the references to the current entity in the project. The
     search is based on the semantic information extracted from the
     sources, this is not a simple text search. The result of the
     search is displayed in the location window, see *Note The
     Locations Tree::.

     This capability requires support for cross references.  This item
     is also accessible through the editor's contextual menu

Previous Tag
     Go to previous tag/location. *Note The Locations Tree::.

Next Tag
     Go to next tag/location. *Note The Locations Tree::.

Source Navigation Contextual Menus
==================================

This contextual menu is available from any source editor by
right-clicking.  If you right click over an entity, or first select
text, the contextual menu will apply to this selection or entity.

Goto declaration of entity
     Go to the declaration/spec of entity. The current entity is
     determined by the word located around the cursor or by the current
     selection if any.  This capability requires support for cross
     references.

Goto body of entity
     Go to the body/implementation of entity.  This capability requires
     support for cross references.

Goto file spec/body
     Open the corresponding spec file if the current edited file is a
     body file, or body file otherwise. This option is only available
     for the Ada language.

References
     This item gives access to different capabilities related to
     listing or displaying references to the current entity or
     selection.

    `Entity calls'
          Open or raise the call graph browser on the specified entity
          and display all the functions called by entity. *Note Call
          Graph::.

    `Entity is called by'
          Open or raise the call graph browser on the specified entity
          and display all the functions calling entity. *Note Call
          Graph::.

          Note that this capability requires a global look up in the
          project cross references, which may take a significant amount
          of time the first time.  After a global look up, information
          is cached in memory, so that further global queries will be
          faster.

    `Find all references to entity'
          *Note Find All References::.

    `Find all local references to entity'
          Find all references to entity in the current file (or in the
          current top level unit for Ada sources).  See *Note Find All
          References:: for more details.

    `Find all writes to entity'
          Find all writes to an entity. This is a search global to the
          project.  See *Note Find All References:: for more details.

    `Find all reads of entity'
          Find all non write accesses to an entity. This is a search
          global to the project.  See *Note Find All References:: for
          more details.

Project Handling
****************

The section on the project explorer (*Note The Project Explorer::) has
already given a brief overview of what the projects are, and the
information they contain.

   This chapter provides more in-depth information, and describes how
such projects can be created and maintained.

Description of the Projects
===========================

Project files and GNAT tools
----------------------------

This section describes what the projects are, and what information they
contain.

   The most important thing to note is that the projects used by GPS are
the same as the ones used by GNAT itself. These are text files (using
the extension `.gpr') which can be edited either manually, with any
text editor, or through the more advanced GPS interface.

   The exact syntax of the project files is fully described in the GNAT
User's Guide (<gnat_ug.html>) and GNAT Reference Manual
(<gnat_rm.html>). This is a recommended reading in any case if you want
to use the more advanced capabilities of the project files, which are
not necessarily all supported by the graphical interface yet.

   GPS cannot edit graphically all the aspects of the project files
(variables for instance are not editable as such, since the GUI makes
their use less necessary). However, it can load any project file, even
those that you have edited manually. On the other hand, you can
manually edit the project files created by GPS.

   You will usually not need to edit the project files manually, since
several graphical tools are provided such as the project wizard (*Note
The Project Wizard::) and the properties editor(*Note The Project
Properties Editor::).

   All the non graphical GNAT tools are project aware, meaning that the
notion of project goes well beyond GPS' user interface, and most
capabilities of the project file can be accessed without using GPS
itself, making the project files very attractive.

   If you are using programming languages other than Ada, the project
files can automatically generate Makefiles through the `gpr2make' tool
provided with GNAT. Round trip editing is not available though, and any
change you make to the generated Makefiles will be lost the next time
the tool is run.

   GPS uses the same mechanisms to locate the project files as GNAT
itself: the projects can be referenced in several ways:

   * absolute paths

   * relative paths These paths, when used in a with line as described
     below, are relative to the location of the project that does the
     with.

   * ADA_PROJECT_PATH If this environment variable is set, it contains
     a colon-separated (or semicolon under Windows) list of directories
     in which the project files are searched.

Contents of project files
-------------------------

The project files contain all the information that describe the
organization of your source files, object files and executables.

   Generally, one project file will not be enough to describe complex
organization. In this case, you will create and use a project hierarchy,
with a root project importing other sub projects. Each of the projects
and sub projects is responsible for its own set of sources (recompile
them with the appropriate switches, put the resulting files in the
right directories, ...).

   Each project contains the following information, among other things
(see the GNAT user's guide for a full list)

   * List of imported projects:    When you are compiling some sources
     from this project, the compiler    (either through GNAT or the
     automatically generated Makefiles) will    first make sure that
     all the imported projects have been correctly    recompiled and
     are up-to-date. This way, dependencies between    source files are
     properly handled.

     If one of the source files of project A depends on some source
     files from project B, then B must be imported by A. If this isn't
      the case, the compiler will complain that some of the source
     files    cannot be found.

     One important rule is that each source file name must be unique in
       the project hierarchy (i.e. a file can not be under control of
     two    different projects. This ensures that the same file will be
     found    no matter what project is managing the source file that
     uses

   * List of source directories:    All the sources managed by a
     project are found in one or more    source directories. Each
     project can have multiple source    directories, and a given
     source directory might be shared by    multiple projects.

   * Object directory:    When the sources of the project are compiled,
     the resulting object    files are put into this object directory.
     There exist exactly one object    directory for each project. If
     you need to split the object files    among multiple object
     directories, you need to create multiple    projects importing one
     another as appropriate.

     When sources from imported sub projects are recompiled, the
     resulting object files are put in the sub project's own object
     directory, and will never pollute the parent's object directory.

   * Exec directory:    When a set of object files is linked into an
     executable, this executable    is put in the exec directory of the
     project file. If this attribute    is unspecified, the object
     directory is used.

   * List of source files:    The project is responsible for managing a
     set of source    files. These files can be written in any
     programming    languages. Currently, the graphical interface
     supports Ada, C and C++.

     The default to find this set of source files is to take all the
     files in the source directories that follow the naming scheme (see
       below) for each language. In addition if you edit the
     project file manually, it is possible to provide an explicit list
     of source    files.

     This attribute cannot be modified graphically yet.

   * List of main units:    The main units of a project (or main files
     in some languages) are    the units that contain the main
     subprogram of the application, and    that can be used to link the
     rest of the application.

     The name of the file is generally related to the name of the
     executable.

     A given project file hierarchy can be used to compile and link
     several executables. GPS will automatically update the Compile, Run
       and Debug menu with the list of executables, based on this list.

   * Naming schemes:    The naming scheme refer to the way files are
     named for each    languages of the project. This is used by GPS to
     choose the language    support to use when a source file is
     opened. This is also used to    know what tools should be used to
     compile or otherwise work with a    source file.

   * Embedded targets and Cross-environments:    GPS fully supports
     cross-environment work: GPS itself can run on a    machine and
     start all the compilation, run and debugger on a remote    host.

     It also supports embedded targets (VxWorks, ...) by specifying
     alternate    names for the build and debug tools.

     The project file contains the information required to log on the
     remote host.

   * Tools:    The project files provide a simple way to change the
     compiler that    should be used to compile the source files, as
     well as the    underlying debugger to use.

   * Switches:    Each tool that is used by GPS (compiler,
     pretty-printer,    debugger, ...) has its own set of switches.
     Moreover, these switches    may depend on what specific file is
     manipulated, and on its language.


Scenarios and Configuration Variables
=====================================

The behavior of projects can be further tailored by the use of
scenarios.

   All the attributes of a project, except its list of imported
projects, can be chosen based on the value of external variables, whose
value is generally coming from the environment, or directly set in GPS
(using the small area on top of the project explorer (*Note The Project
Explorer::).

   This can for instance be used to compile all the sources either in
debug mode (so that the executables can be run in the debugger), or in
optimized mode (to reduce the space and increase the speed when
delivering).  In this case, all the attributes (source directories,
tools, ...) remain the same, except the switches. It would be more
difficult to maintain a completely separate hierarchy of project, and
it is much more efficient to create a new configuration variable and
edit the switches for the appropriate scenario (*Note The Project
Properties Editor::).

Creating new configuration variables
------------------------------------

Creating a new scenario variable is done through the contextual menu
(right-click) in the project explorer. Select the menu `Add
Configuration Variable'. This opens the following dialog:

   There are two main areas in this dialog: in the top line, you specify
the name of the variable. This name is used for two purposes:

   * It is displayed in the project explorer

   * This is the name of the environment variable from which the
     initial value is read. When GPS is started, all configuration
     variables are initialized from the environment, although you can of
     course change them as many times as you want later on.


   If you click on the arrow on the right of this name area, GPS will
display the list of all the environment variables that are currently
defined. However, you don't need to pick the name of an existing
variable, neither must the variable exist when GPS is started.

   The second part of this dialog is the list of authorized value for
this variable. Any other value will generate an error reported by GPS,
and the project won't be loaded as a result.

   One of these values is the default value (the one whose button in the
Default column is selected). This means that if the environment
variable doesn't exist when GPS is started, GPS will behave as if it
did exist with this default value.

   The list of possible values can be edited through the `Remove',
`Add' and `Rename' buttons, although you can also simply click on the
value itself to change it.

Editing existing configuration variables
----------------------------------------

If at least one configuration variable is defined in your project, the
area on top of the project explorer will contain something similar to:

   This screen shot shows two configuration variables, named `Build'
and `OS', with their current value (resp. `Debug' and `Unix').

   You can easily change the current value of any of these variables by
clicking on the arrow on the right of the value. This will display a
pop-up window with the list of possible values, from which you select
the one you wish to use.

   As soon as a new value is selected, GPS will recompute the project
explorer (in case the source directories, object directories or list of
source files has changed). A number of things will also be updated
(like the list of executables in the `Compile', `Run' and `Debug'
menus).

   Currently, GPS will not recompute the contents of the various
browsers (call graph, dependencies, ...) for this new project. This
would be too expensive to do every time the value changes, and
therefore you need to explicitly request an update.

   You can change the list of possible values for a configuration
variable at any time by clicking on the button to the far left of the
variable's name. This will pop up the same dialog that is used to create
new variables

   Removing a variable is done by clicking on the button immediately to
the left of the variable's name. GPS will then display a confirmation
dialog.

   If you confirm that you want to delete the variable, GPS will simply
remove the variable, and from now on act as if the variable always had
the value it had when it was deleted.

The Project Explorer
====================

The project explorer, as mentioned in the general description of the
GPS window, is one of the two explorers found by default on the left of
the window. It shows in a tree structure the project hierarchy, along
with all the source files belonging to the project, and the entities
declared in the source files.

   It is worth noting that the explorer provides a tree representation
of the project hierarchy. If a project is imported by multiple other
projects in the hierarchy, then this project will appear multiple times
in the explorer.

   Likewise, if you have edited the project manually and have used the
`limited with' construct to have cycles in the project dependencies,
the cycle will expand infinitely. For instance, if project `a' imports
project `b', which in turns imports project `a' through a `limited
with' clause, then expanding the node for `a' will show `b'. In turn,
expanding the node for `b' will show a node for `a', and so on.

   The contextual menu in this explorer provides a number of items to
modify the project hierarchy (what each project imports), as well as to
visualize and modify the attributes for each projects (compilation
switches, naming scheme, ...)

   The following entries are available in the contextual menu:

`Show Projects Imported by...'
     This item will open a new window in GPS, the project browser, which
     displays graphically the relationships between each project in the
     hierarchy.

`Save The Project...'
     This item can be selected to save a single project in the hierarchy
     after it was modified. Modified but unsaved projects in the
     hierarchy have a special icon (an red exclamation mark is drawn on
     top of the standard icon). If you would rather save all the
     modified projects in a single step, use the menu bar item
     `Project->Save All'.

`Edit Project Properties'
     This item will open a new dialog, and give access to all the
     attributes of the project: tool switches, naming schemes, source
     directories, ... *Note The Project Properties Editor::.

`Add Dependency...'
     This menu and its two sub-menus are the primary way to change the
     relationship between projects in the hierarchy. You can either add
     a dependency on an already existing project, or a dependency on a
     newly created project.

`Remove Dependency...'
     This menu item is the opposite of the previous one, and will
     remove a dependency between two projects

`Add Configuration Variable'
     This menu item should be used to add new configuration variables,
     as described in *Note Scenarios and Configuration Variables::.

`Edit Project Source File'
     This menu will load the project file into an editor, so that you
     can manually edit it. This should be used if you need to access
     some features of the project files that are not accessible
     graphically (renames statements, variables, ...)

   Any time one or several projects are modified, the contents of the
explorer is automatically refreshed. No project is automatically saved.
This provides a simple way to temporarily tests new values for the
project attributes.  Unsaved modified projects are shown with a special
icon in the project explorer, displaying a red exclamation mark on top
of the standard icon:

The Project Menu
================

   The menu bar item `Project' contains several commands that generally
act on the whole project hierarchy. If you only want to act on a single
project, use the contextual menu in the project explorer.

   Some of these menus apply to the currently selected project. This
notion depends on what window is currently active in GPS: if it is the
project explorer, the selected project is either the selected node (if
it is a project), or its parent project (for a file, directory, ...).
If the currently active window is an editor, the selected project is
the one that contains the file.

   In all cases, if there is no currently selected project, the menu
will apply to the root project of the hierarchy.

   These commands are:

`New'
     This menu will open the project wizard (*Note The Project
     Wizard::), so that you can create new projects. On exit, the
     wizard asks whether the newly project should be loaded. If you
     select `Yes', the newly project will replace the currently loaded
     project hierarchy.

`Open'
     This menu opens a file selection dialog, so that any existing
     project can be loaded in GPS. The newly loaded project replaces
     the currently loaded project hierarchy. GPS works on a single
     project hierarchy at a time.

`Recent'
     This menu can be used to easily switch between the last projects
     that were loaded in GPS.

`Edit Project Properties'
     This menu applies to the currently selected project, and will open
     the project properties dialog for this project.

`Save All'
     This will save all the modified projects in the hierarchy.

`Edit File Switches'
     This menu applies to the currently selected project. This will
     open a new window in GPS, listing all the source files for this
     project, along with the switches that will be used to compile
     them, *Note The Switches Editor::.

`Recompute Project'
     Recompute the contents of the project after modifications outside
     of GPS. In particular, it will take into account new files added
     externally to the source directories.  This isn't needed for
     modifications made through GPS. Note also that this doesn't
     re-parse the physical project file on disk. Instead, you can
     reopen the project if you have done manual modifications to it.

`File View and Project View'
     These two menus will open (or raise if they are already open) the
     explorers on the left side of the GPS window.

The Project Wizard
==================

The project wizard allows you to create in a few steps a new project
file.  It has a number of pages, each dedicated to editing a specific
set of attributes for the project.

   The most usual way to access this wizard is through the menu
`Project->New...' On exit, the wizard will ask whether the newly
created project should replace the currently loaded ones.

   The project wizard is also activated when a new dependency is created
between two projects, through the contextual menu in the project
explorer.

   The wizard gives access to the following list of pages:

   * Project Naming

   * VCS Selection

   * Source Directories Selection

   * Build Directory

   * Naming Scheme

   * Main Units

   * Switches

Project Naming
--------------

This is the first page displayed by the wizard.

   You must enter the name and location of the project to create. This
name must be a valid Ada identifier (i.e. start with a letter,
optionally followed by a series of digits, letters or underscores).
Spaces are not allowed. Likewise, reserved Ada keywords must be
avoided. If the name is invalid, GPS will display an error message when
you press the `Forward' button.

   In this page, you should also select what languages the source files
in this project are written in. Currently supported are `Ada', `C' and
`C++'. Multiple languages can be used for a single project.

   The last part of this page is used to indicate how the path should be
stored in the generated project file. Most of the time, this setting
will have no impact on your work. However, if you wish to edit the
project files by hand, or be able to duplicate a project hierarchy to
another location on your disk, it might be useful to indicate that
paths should be stored as relative paths (they will be relative to the
location of the project file).

VCS Selection
-------------

The second page in the project wizard selected which Version Control
system is used for the source files of this project.

   GPS doesn't attempt to automatically guess what it should use, so you
must specify it if you want the VCS operations to be available to you.

   The two actions `Log checker' and `File checker' are the name and
location of programs to be run just prior an actual commit of the files
in the Version Control System. These should be used for instance if you
wish to enforce style checks before a file is actually made available
to the other persons in your team.

   If left blank, no program will be run.

Source Directories Selection
----------------------------

This page lists and edits the list of source directories for the
project. Any number of source directory can be used (the default is to
use the directory which contains the project file, as specified in the
first page of the wizard).

   If you do not specify any source directory, no source file will be
associated with the project, since GPS wouldn't know where to look for
them.

   To add source directories to the project, select the project in the
top frame, and click on the down arrow. This will add the directory to
the bottom frame, which contains the current list of source directories.

   You can also add a directory and all its subdirectories recursively
by using the contextual menu in the top frame. This contextual menu also
provides an entry to create new directories, if needed.

   To remove source directories from the project, select the project in
the bottom frame, and click on the up arrow, or use the contextual menu.

   All the files in these directories that match one of the language
supported by the project are automatically associated with that project.

   The relative sizes of the top and bottom frame can be changed by
clicking on the separation line between the two frames and dragging the
mouse up or down.

Build Directory
---------------

The object directory is the location where the files resulting from the
compilation of sources (`.o' files for instance) are put.

   One object directory is associated for each project.

   The exec directory is the location where the executables are put. By
default, this is the same directory as the object directory.

Naming Scheme
-------------

A naming scheme indicates the file-naming conventions used in the
different languages supported by a given project.  For example, all
`.adb' files are Ada files, all `.c' files are C files.

   GPS is very flexible in that respect, and allows you to specify the
default extension for the files in this language. GPS makes a
distinction between spec (or header) files, which generally contains no
executable code, only declarations, and body files which contain the
actual code. For languages other than Ada, this header file is used
rather than the body file when you select `Go To Declaration' in the
contextual menu of editors.

   In a language like Ada, the distinction between spec and body is
part of the definition of the language itself, and you should be sure
to specify the appropriate extensions.

   The default naming scheme for Ada is GNAT's naming scheme (`.ads'
for specs and `.adb' for bodies). In addition, a number of predefined
naming schemes for other compilers are available in the first combo box
on the page. You can also create your own customized scheme by entering
a free text in the text entries.

   For all languages, GPS accepts exceptions to this standard naming
scheme. For instance, this let you specify that in addition to using
`.adb' for Ada body files, the file `foo.ada' should also be considered
as an Ada file.

   The list of exceptions is displayed in the bottom list of the naming
scheme editor. To remove entries from that list, select the line you
want to remove, and then press the <Del> key.  The contents of the
lines can be edited interactively, by double-clicking on the line and
column you want to edit.

   To add new entries to this list, use the three fields at the bottom
of the window, and press the update button.

Main Units
----------

The main units for a project are the files that should be compiled and
linked to obtain executables.

   Typically, for C applications, these are the files that contain the
`main()' function. For Ada applications, these are the files that
contain the main subprogram for the partition.

   These files are treated specially by GPS. Some sub-menus of `Build'
and `Debug' will have predefined entries for the main units, which make
it more convenient to compile and link your executables.

   To add main units click on the `Add' button. This opens a file
selection dialog. No check is currently done that the selected file
belongs to the project, but GPS will complain later if it doesn't.

   When compiled, each main unit will generate an executable, whose name
is visible in the second column in this page. If you are using a recent
enough version of GNAT (3.16 or more recent), you can change the name
of this executable by clicking in the second column and changing the
name interactively.

Switches
--------

The last page of the project wizard is used to select the default
switches to be used by the various tools that GPS calls (compiler,
linker, binder, pretty printer, ...).

   This page appears as a notebook, where each page is associated with a
specific tool. All these pages have the same structure:

Graphical selection of switches
     The top part of each page contains a set of buttons, combo boxes,
     entry fields, ... which give fast and intuitive access to the most
     commonly used switches for that tool.

Textual selection of switches
     The bottom part is an editable entry field, where you can directly
     type the switches. This makes it easier to move from an older
     setup (e.g. Makefile, script) to GPS, by copy-pasting switches.

   The two parts of the pages are kept synchronized at any time:
clicking on a button will edit the entry field to show the new switch;
adding a new switch by hand in the entry field will activate the
corresponding button if there is one.

   Any switch can be added to the entry field, even if there is no
corresponding button. In this case, GPS will simply forward it to the
tool when it is called, without trying to represent it graphically.

The Project Properties Editor
=============================

The project properties editor gives you access at any time to the
properties of your projects. It is accessible through the menu
`Project->Edit Project Properties', and through the contextual menu
`Edit project properties' on any project item, e.g. from the Project
View or the Project Browser.

   If there was an error loading the project (invalid syntax,
non-existing directories, ...), a warning dialog is displayed when you
select the menu. This reminds you that the project might be only
partially loaded, and editing it might result in the loss of data. In
such cases, it is recommended that you edit the project file manually,
which is doable directly from the pop-up dialog.

   Fix the project file as you would for any text file, and then reload
it manually (through the `Project->Open...' or `Project->Recent' menus.

   This editor is divided into three parts:

The attributes editor
     The contents of this editor is very similar to that of the project
     wizard (*note The Project Wizard::). In fact, all pages but the
     `General' page are exactly the same, and you should therefore read
     the description for these in the project wizard chapter.

     The general page gives access to more attributes than the general
     page of the project wizard does. In addition, you can select the
     name of all the external tools that GPS uses (compilers for the
     various languages, linker, pretty-printer, ...).

The project selector
     This area, in the top-right corner of the properties editor,
     contains a list of all the projects in the hierarchy. The value in
     the attributes editor is applied to all the selected projects in
     this selector. You can never unselect the project for which you
     activated the contextual menu.

     Clicking on the right title bar (`Project') of this selector will
     sort the projects in ascending or descending order.

     Clicking on the left title bar (untitled) will select or unselect
     all the projects.

     This selector has two different possible presentations, chosen by
     the toggle button on top: you can either get a sorted list of all
     the projects, each one appearing only once. Or you can have the
     same project hierarchy as displayed in the project explorer.

The scenario selector
     This area, in the bottom-right corner of the properties editor,
     lists all the scenario variables declared for the project
     hierarchy. By selecting some or all of their values, you can chose
     to which scenario the modifications in attributes editor apply.

     Clicking on the left title bar (untitled, on the left of the
     `Scenario' label) will select all values of all variables.

     To select all values of a given variable, click on the
     corresponding check button.

The Switches Editor
===================

The switches editor, available through the menu `Project->Edit
Switches', lists all the source files associated with the selected
project.

   For each file, the compiler switches are listed. These switches are
displayed in gray if they are the default switches defined at the
project level (*note The Project Properties Editor::). They are defined
in black if they are specific to a given file.

   Double-clicking in the switches column allows you to edit the
switches for a specific file. It is possible to edit the switches for
multiple files at the same by selecting them before displaying the
contextual menu (`Edit switches for all selected files'.

   When you double-click in one of the columns that contain the
switches, a new dialog is opened that allows you to edit the switches
specific to the selected files.

   This dialog has a button titled `Revert'. Clicking on this button
will cancel any file-specific switch, and revert to the default
switches defined at the project level.

The Project Browser
===================

The project graph is a special kind of browser (*note Source
Browsing::). It shows the dependencies between all the project in the
project hierarchy. Two items in this browser will be linked if one of
them imports the other.

   It is accessed through the contextual menu in the project explorer,
by selecting the `Show projects imported by...' item, when
right-clicking on a project node.

   Clicking on the left arrow in the title bar of the items will display
all the projects that import that project. Similarly, clicking on the
right arrow will display all the projects that are imported by that
project.

   The contextual menu obtained by right-clicking on a project item
contains several items. Most of them are added by the project editor,
and gives direct access to editing the properties of the project,
adding dependencies...  *Note The Project Explorer (Editing Projects)::.

   Some new items are added to the menu:

`Locate in explorer'
     Selecting this item will switch the focus to the project explorer,
     and highlight the first project node found that matches the
     project in the browser item. This is a convenient way to get
     information like the list of directories or source files for that
     project.

`Show dependencies'
     This item plays the same role as the right arrow in the title bar,
     and display all the projects in the hierarchy that are imported
     directly by the selected project

`Show recursive dependencies'
     This item will display all the dependencies recursively for the
     project (i.e. the project it imports directly, and the projects
     that are imported by them, and so on).

`Show projects depending on'
     This item plays the same role as the left arrow in the title bar,
     and display all the projects that import directly the selected
     project.

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.

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::).

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.

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

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.

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.

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

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.

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.

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.

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'.

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).

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.


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.

Using the Source Editor when Debugging
======================================

When debugging, the left area of each source editor provides the
following information:

Lines with code
     In this area, blue dots are present next to lines for which the
     debugger has debug information, in other words, lines that have
     been compiled with debug information and for which the compiler
     has generated some code.  Currently, there is no check when you
     try to set a breakpoint on a non dotted line: this will simply
     send the breakpoint command to the underlying debugger, and
     usually (e.g in the case of gdb) result in setting a breakpoint at
     the closest location that matches the file and line that you
     specified.

Current line executed
     This is a green arrow showing the line about to be executed.

Lines with breakpoints
     For lines where breakpoints have been set, a red mark is displayed
     on top of the blue dot for the line. You can add and delete
     breakpoints by clicking on this area (the first click will set a
     breakpoint, the second click will remove it).

   The second area in the source window is a text window on the right
that    displays the source files, with syntax highlighting.     If you
leave the cursor over a variable, a tooltip will    appear showing the
value of this variable. Automatic tooltips can be    disabled in the
preferences menu.     See *Note preferences dialog::.

   When the debugger is active, the contextual menu of the source window
  contains a sub menu called `Debug' providing the following entries.

   Note that these entries are dynamic: they will apply to the entity
found under the cursor when the menu is displayed (depending on the
current language). In addition, if a selection has been made in the
source window the text of the selection will be used instead. This
allows you to display more complex expressions easily (for example by
adding some comments to your code with the complex expressions you want
to be able to display in the debugger).

Print selection
     Prints the selection (or by default the name under the cursor) in
     the debugger console.

Display selection
     Displays the selection (or by default the name under the cursor)
     in the data window. The value will be automatically refreshed each
     time the process state changes (e.g after a step or a next
     command). To freeze the display in the canvas, you can either
     click on the corresponding icon in the data window, or use the
     contextual menu for the specific item (see *Note The Data Window::
     for more information).

Print selection.all
     Dereferences the selection (or by default the name under the
     cursor) and prints the value in the debugger console.

Display selection.all
     Dereferences the selection (or by default the name under the
     cursor) and displays the value in the data window.

View memory at address of selection
     Brings up the memory view dialog and explores memory at the
     address of the selection.

Set Breakpoint on Line xx
     Sets a breakpoint on the line under the cursor, in the current
     file.

Set Breakpoint on selection
     Sets a breakpoint at the beginning of the subprogram named
     selection

Continue Until Line xx
     Continues execution (the program must have been started
     previously) until it reaches the specified line.

Show Current Location
     Jumps to the current line of execution. This is particularly
     useful after navigating through your source code.

The Assembly Window
===================

   It is sometimes convenient to look at the assembly code for the
subprogram or source line you are currently debugging.

   You can open the assembly window by using the menu
`Debug->Data->Assembly'.

   The current assembly instruction is highlighted with a green arrow
on its left.  The instructions corresponding to the current source line
are highlighted in red by default. This allows you to easily see where
the program counter will point to, once you have pressed the "Next"
button on the tool bar.

   Moving to the next assembly instruction is done through the "Nexti"
(next instruction) button in the tool bar. If you choose "Stepi"
instead (step instruction), this will also jump to the subprogram being
called.

   For efficiency reasons, only a small part of the assembly code
around the current instruction is displayed.  You can specify in the
*Note preferences dialog:: how many instructions are displayed by
default. Also, you can easily display the instructions immediately
preceding or following the currently displayed instructions by pressing
one of the <Page up> or <Page down> keys, or by using the contextual
menu in the assembly window.

   A convenient complement when debugging at the assembly level is the
ability of displaying the contents  of machine registers.  When the
debugger supports it (as gdb does), you can select the `Data->Display
Registers' menu to get an item in the canvas that will show the current
contents of each machine register, and that will be updated every time
one of them changes.

   You might also choose to look at a single register.  With gdb,
select the `Data->Display Any Expression', entering something like

     output /x $eax

   in the field, and selecting the toggle button "Expression is a
subprogram call". This will create a new canvas item that will be
refreshed every time the value of the register (in this case eax)
changes.

The Debugger Console
====================

This is the text window located at the bottom of the main window.  In
this console, you have direct access to the underlying debugger, and
can send commands (you need to refer to the underlying debugger's
documentation, but usually typing help will give you an overview of the
commands available).

   If the underlying debugger allows it, pressing <Tab> in this window
will provide completion for the command that is being typed (or for its
arguments).

   There are also additional commands defined to provide a simple text
interface to some graphical features.

   Here is the complete list of such commands. The arguments between
square brackets are optional and can be omitted.

`graph (print|display) expression [dependent on display_num] [link_name name]'
     This command creates a new item in the canvas, that shows the
     value of EXPRESSION. EXPRESSION should be the name of a variable,
     or one of its fields, that is in the current scope for the
     debugger.

     The command `graph print' will create a frozen item, that is not
     automatically refreshed when the debugger stops, whereas `graph
     display' displays an automatically refreshed item.

     The new item is associated with a number, that is visible in its
     title bar.  These numbers can be used to create links between the
     items, using the second argument to the command, DEPENDENT ON. The
     link itself (i.e. the line) can be given a name that is
     automatically displayed, using the third argument.

`graph (print|display) `command`'
     This command is similar to the one above, except it should be used
     to display the result of a debugger command in the canvas.

     For instance, if you want to display the value of a variable in
     hexadecimal rather than the default decimal with gdb, you should
     use a command like:

          graph display `print /x my_variable`

     This will evaluate the command between back-quotes every time the
     debugger stops, and display this in the canvas. The lines that
     have changed will be automatically highlighted (in red by default).

     This command is the one used by default to display the value of
     registers for instance.

`graph (enable|disable) display display_num [display_num ...]'
     This command will change the refresh status of items in the
     canvas. As explained above, items are associated with a number
     visible in their title bar.

     Using the `graph enable' command will force the item to be
     automatically refreshed every time the debugger stops, whereas the
     `graph disable' command will freeze the item.

`graph undisplay display_num'
     This command will remove an item from the canvas

`view (source|asm|source_asm)'
     This command indicates what should be displayed in the source
     window.  The first option indicates that only the source code
     should be visible, the second one specifies that only the assembly
     code should be visible, and the last one indicates that both
     should be displayed.

Version Control System
**********************

   GPS offers the possibility for multiple developers to work on the
same project, through the integration of version control systems (VCS).
Each project can be associated to a VCS, through the `VCS' tab in the
Project property editor. *Note The Project Properties Editor::.

   The systems that are currently supported in GPS are CVS and
ClearCase.  It is recommended that you first get familiar with the
version control system that you intend to use in GPS first, since many
concepts used in GPS assume basic knowledge of the underlying system.

   Associating a VCS to a project enables the use of basic VCS features
on the source files contained in the project. Those basic features
typically include the checking in and out of files, the querying of
file status, file revision history, comparison between various
revisions, and so on.

   Administration of VCS systems is not handled by GPS at this stage.
Therefore, before working on a project using version control system,
make sure that the system is properly set-up before launching GPS.

   Note: the set-up must make sure that the VCS commands can be
launched without entering a password.

The VCS Explorer
================

The VCS Explorer provides an overview of source files and their status.

   The easiest way to bring up the VCS Explorer is through the menu
`VCS->Explorer'. The Explorer can also be brought up using the
contextual menu `Version Control->Query status' on files, directories
and projects in the file and project views, and on file editors. *Note
The Version Control Contextual Menu::.

   The VCS Explorer contains the following columns:

Status
     Shows the status of the file. This column can be sorted by
     clicking on the header. The different possible status for files
     are the following:

    `Unknown'
          The status is not yet determined or the VCS repository is not
          able to give this information (for example if it is
          unavailable, or locked).

    `Not registered'
          The file is not known to the VCS repository.

    `Up-to-date'
          The file corresponds to the latest version in the
          corresponding branch on the repository.

    `Removed'
          The file still exists locally but is known to have been
          removed from the VCS repository.

    `Modified'
          The file has been modified by the user or has been explicitly
          opened for editing.

    `Needs merge'
          The file has been modified locally and on the repository.

    `Needs update'
          The file has been modified in the repository but not locally.

Log
     This column indicates whether a revision log exists for this file.

File
     The name of the file. This column can be sorted by clicking on the
     header.

Working rev.
     Indicates the version of the local file.

Head rev.
     Indicates the most recent version of the file in the repository.

   The VCS Explorer supports multiple selections. To select a single
line, simply left-click on it. To select a range of lines, select the
first line in the range, then hold down the <Shift> key and select the
last line in the range. To add or remove single columns from the
selection, hold down the <Control> key and left-click on the columns
that you want to select/unselect.

   The explorer also provides an interactive search capability allowing
you to quickly look for a given file name. The default key to start an
interactive search is <Ctrl-i>. See *Note Interactive Search:: for more
details.

   The VCS contextual menu can be brought up from the VCS explorer by
left-clicking on a selection or on a single line. *Note The Version
Control Contextual Menu::.

The VCS Menu
============

Basic VCS operations can be accessed through the VCS menu. Most of
these functions act on the current selection, i.e. on the selected items
in the VCS Explorer if it is present, or on the currently selected file
editor, or on the currently selected item in the Project/File View. In
most cases, the VCS contextual menu offers more control on VCS
operations. *Note The Version Control Contextual Menu::.

Explorer
     Open or raise the VCS Explorer. *Note The VCS Explorer::.

Update all projects
     Update the source files in the current project, and all imported
     sub-projects, recursively.

Query status for all projects
     Query the status of all files in the project and all imported
     sub-projects.

Update
     Update the currently selected item (file, directory or project).

Commit
     Submits the changes made to the file to the repository, and queries
     the status for the file once the change is made.

     It is possible to tell GPS to check the file before the actual
     commit happens. This is done by specifying a `File checker' in the
     `VCS' tab of the project properties dialog. This `File checker' is
     in fact a script or executable that takes an absolute file name as
     argument, and displays any error message on the standard output.
     The VCS commit operation will actually occur only if nothing was
     written on the standard output.

     It is also possible to check the change-log of a file before
     commit, by specifying a `Log checker' in the project properties
     dialog. This works on change-log files in the same way as the
     `File checker' works on source files.

Start Editing
     Open the currently selected file for writing. On some VCS systems,
     this is a necessary operation, and on other systems it is not.

View revision history
     Show the revision logs for all previous revisions of this file.

Compare against head rev.
     Show a visual comparison between the local file and the most recent
     version of that file in the repository.

Compare against working rev.
     Show a visual comparison between the local file and the
     corresponding version of that file in the repository.

Compare working against head rev.
     Show a visual comparison between the corresponding version of the
     file in the repository and the most recent version of that file.

Annotate
     Display the annotations for the file, i.e. the information for each
     line of the file showing the revision corresponding to that file,
     and additional information depending on the VCS system.

Remove annotations
     Remove the annotations from the selected file.

Edit revision log
     Edit the current revision log for the selected file.

Add to repository
     Add a file to the repository.

Remove from repository
     Remove a file from the repository.

The Version Control Contextual Menu
===================================

This section describes the version control contextual menu displayed
when you right-click on an entity (e.g. a file, a directory, a project)
from various parts of GPS, including the project explorer, the source
editor and the VCS Explorer.

   Depending on the context, some of the items described in this
section won't be shown, which means that they are not relevant to the
current context.

Query status
     Query the status of the selected item. Brings up the VCS Explorer.

Update
     Update the selected item. *Note Update::.

Commit via revision log
     This menu item is titled Commit when a revision log has already
     been created.  *Note Commit::.

Start editing
     Open the selected file for editing. *Note Start Editing::.

View revision history
     View the revision history for the selected file. *Note View
     revision history::.

Compare against head rev.
     Compare selected files. *Note Compare against head::.

Compare against working rev.
     Compare selected files. *Note Compare against working::.

Compare working against head rev.
     Compare selected files. *Note Compare working against head::.

Annotate
     Enable annotations for the selected files.  *Note Annotate::.

Remove annotations
     Remove annotations for the selected files.

Edit revision log
     Edit the revision log file corresponding to the selected files.

Remove revision log
     Deletes the revision log file corresponding to the selected files.

Add to repository
     Add the selected items to the repository.

Remove from repository
     Remove the selected items from the repository.

Directory
     Only available when the current context contains directory
     information

    Query status for directory
          Query status for the files contained in the selected
          directory.

    Query status for directory recursively
          Query status for the files in the selected directory and all
          subdirectories recursively, links not included.

    Update directory
          Update the files in the selected directory.

    Update directory recursively
          Update the files in the selected directory and all
          subdirectories recursively, links not included..

Project
     Only available when the current context contains project
     information

    List all files in project
          Brings up the VCS Explorer with all the source files
          contained in the project.

    Query status for project
          Queries the status for all the source files contained in the
          project.

    Update project
          Updates all the source files in the project.

    List all files in project and subprojects
          Brings up the VCS Explorer with all the source files
          contained in the project and all imported subprojects.

    Query status for project and subprojects
          Queries the status for all the source files contained in the
          project and all imported subprojects.

    Update project and subprojects
          Updates all the source files in the project and all imported
          subprojects.

Hide up-to-date files
     Only available from the VCS Explorer.  Filter out up-to-date
     files, that is files that have not been modified locally and that
     do not need to be updated.

Hide non registered files
     Only available from the VCS Explorer.  Filter out non registered
     files, that is files unknown to the version control system, or
     whose information could not be retrieved (e.g. the version control
     server is temporarily unavailable).

Tools
*****

The Tools Menu
==============

The `Tools' menu gives access to additional tools. Some items are
currently disabled, meaning that these are planned tools not yet
available.

   The list of active items includes:

Shell Console
     Open a shell console at the bottom are of GPS.  *Note The Shell
     Window::.

Call Graph
     *Note Call Graph::.

Dependency Browser
     *Note Dependency Browser::.

Entity Browser
     *Note Entity Browser::.

Compare
     *Note Visual Comparison::.

Visual Comparison
=================

Note that this tool is in a preliminary stage. More capabilities will
be added in the future such as comparison of multiple files, interactive
merge, ....

   The visual comparison, available either from the VCS menus or from
the Tools menu, provide a way to display graphically differences
between two files, or two different versions of the same file.

   This tool is based on the standard text command `diff', available on
all Unix systems. Under Windows, you need to provide a proper
equivalent, by e.g. installing a set of Unix tools such as cygwin
(<http://www.cygwin.com>).

   The dialog is composed of two main areas: on the left side, the
reference file is displayed; on the right side, the modified file.

   By default, only chunks of differences are displayed, with a number
of lines of context around, that can be parametrized in the preferences
dialog.

   Vertical and horizontal scroll bars are available for each file that
allow you to scroll both files at the same time. In addition, empty
lines are added when needed so that the two files can always be
displayed side by side and stay synchronized.

   Colors are used to display the different kinds of chunks:

gray
     This color is used for all the chunks on the reference (left)
     file. Only the modified (right) file is displayed with different
     colors.

blue
     This color is used to display lines that have been modified
     compared to the reference file.

green
     Used to display lines added compared to the reference file; in
     other words, lines that are not present in the reference file.

red
     Used to display lines removed from the reference file; in other
     words, lines that are present only in the reference file.

Code Fixing
===========

GPS provides an interactive way to fix or improve your source code,
based on messages (errors and warnings) generated by the GNAT compiler.

   This capability is integrated with the Locations tree (see *Note The
Locations Tree::): when GPS can take advantage of a compiler message,
an icon is added on the left side of the line.

   For a simple fix, a wrench icon is displayed. If you click with the
left button on this icon, the code will be fixed automatically, and you
will see the change in the corresponding source editor. An example of a
simple fix, is the addition of a missing semicolon.

   You can also check what action will be performed by clicking on the
right button which will display a contextual menu with a text
explaining the action that will be performed. Similarly, if you display
the contextual menu anywhere else on the message line, a sub menu
called Code Fixing gives you access to the same information. In the
previous example of a missing semicolon, the menu will contain an entry
labeled Add expected string ";".

   Once the code change has been performed, the tool icon is no longer
displayed.

   For more complex fixes, where more than one change is possible, the
icon will display in additional of the tool, a red question mark. In
this case, clicking on the icon will display the contextual menu
directly, giving you access to the possible choices. For example, this
will be the case when an ambiguity is reported by the compiler for
resolving an entity.

Working in a Cross Environment
******************************

This chapter explains how to adapt your project and configure GPS when
working in a cross environment.

Customizing your Projects
=========================

This section describes some possible ways to customize your projects
when working in a cross environment. For more details on the project
capabilities, see *Note Project Handling::.

   When using the project editor to modify the project's properties, two
areas are particularly relevant to cross environments: `Tools' and
`Cross environment', part of the `General' page.

   In the `Tools' section, you will typically need to change the name of
the compiler(s) and the debugger, as well as gnatls' name if you are
using Ada.

   For example, assuming you have an Ada project, and using a powerpc
VxWorks configuration. You will set the Ada compiler to
`powerpc-wrs-vxworks-gnatmake'; Gnatls to `powerpc-wrs-vxworks-gnatls'
and Debugger to `powerpc-wrs-vxworks-gdb'.

   If you are using an alternative run time, e.g. a soft float run time,
you need to add the option `--RTS=soft-float' to the Gnatls property,
e.g: `powerpc-wrs-vxworks-gnatls --RTS=soft-float', and add this same
option to the Make switches in the switch editor.  See *Note Switches::
for more details on the switch editor.

   To modify your project to support configurations such as multiple
targets, or multiple hosts, you can create scenario variables, and
modify the setting of the Tools parameters based on the value of these
variables. See *Note Scenarios and Configuration Variables:: for more
information on these variables.

   For example, you may want to create a variable called `Target' to
handle the different kind of targets handled in your project:

Target
     Native, Embedded

Target
     Native, PowerPC, M68K

   Similarly, you may define a `Board' variable listing the different
boards used in your environment and change the Program host and Protocol
settings accordingly.

   In some cases, it is useful to provide a different body file for a
given package (e.g. to handle target specific differences). A possible
approach in this case is to use a configuration variable (e.g. called
`TARGET'), and specify a different naming scheme for this body file (in
the project properties, `Naming' tab), based on the value of `TARGET'.

Debugger Issues
===============

This section describes some debugger issues that are specific to cross
environments. You will find more information on debugging by reading
*Note Debugging::.

   To connect automatically to the right remote debug agent when
starting a debugging session (using the menu `Debug->Initialize'), be
sure to specify the `Program host' and `Protocol' project properties,
as described in the previous section.

   For example, if you are using the Tornado environment, with a target
server called `target_ppc', set the `Protocol' to `wtx' and the
`Program host' to `target_ppc'.

   Once the debugger is initialized, you can also connect to a remote
agent by using the menu `Debug->Debug->Connect to Board...'. This will
open a dialog where you can specify the target name (e.g. the name of
your board or debug agent) and the communication protocol.

   In order to load a new module on the target, you can select the menu
`Debug->Debug->Load File...'.

   If a module has been loaded on the target and is not known to the
current debug session, use the menu `Debug->Debug->Add Symbols...' to
load the symbol tables in the current debugger.

Customizing and Extending GPS
*****************************

The Preferences Dialog
======================

This dialog, available through the menu `Edit->Preferences', allows you
to modify the global preferences of GPS.  To enable the new
preferences, you simply need to confirm by pressing the `OK' button. To
test your changes, you can use the `Apply' button. Pressing the
`Cancel' button will undo all your changes.

   Each preference is composed of a label displaying the name of the
preference, and an editing area to modify its value. If you leave to
mouse over the label, a tool tip will be displayed giving an on-line
help on the preference.

   The preferences dialog is composed of eight areas, accessible
through the tabs at the left of the dialog, labeled General, Editor,
Debugger, Helpers, Browsers, Visual Diff, Messages and Project.  Each
page corresponds to a section of preferences.

   * General

     The general preferences are composed of two pages available at the
     top of the right area: General and Windows

    General

         Default font
               The default font used in GPS

         Key theme
               Name of key theme to use. The key themes determines the
               key bindings used by the various visual objects, in
               particular the source editor.  Values currently
               supported are `Emacs' and `Default'

         Character set
               Name of character set to use for displaying text. The
               default value is ISO-8859-1, which corresponds to
               Latin-1 (Western European) characters.

         Dynamic key bindings
               Whether the menu key bindings can be changed
               interactively.  *Note Redefining key bindings::.

         Display splash screen
               Whether a splash screen should be displayed when
               starting GPS.

         Display welcome window
               Whether GPS should display the welcome window for the
               selection of the project to use.

         Show text in tool bar
               Whether the tool bar should show both text and icons, or
               only icons.

         Auto save
               Whether unsaved files and projects should be saved
               automatically before calling external tools (e.g. before
               a build).

         Save desktop on exit
               Whether the desktop (size and positions of all windows)
               should be saved when exiting.

         Aliases key
               Key to press to expand an alias in a source editor or a
               text entry anywhere in GPS.

    Windows
          This section specifies preferences that apply to the Multiple
          Document Interface described in *Note Multiple Document
          Interface::.

         Opaque
               If True, items will be resized or moved opaquely when
               not maximized.

         Destroy floats
               If False, closing the window associated with a floating
               item will put the item back in the main GPS window, but
               will not destroy it. If True, the item is destroyed.

         All floating
               If True, then all the windows will be floating by
               default, i.e. be under the control of your system
               (Windows) or your window manager (Unix machines). This
               replaces the MDI.

         Background color
               Color to use for the background of the MDI.

         Title bar color
               Color to use for the title bar of unselected items.

         Selected title bar color
               Color to use for the title bar of selected items.

         Select Window
               The key shortcut used to switch between windows.

   * Editor
    General

         Strip blanks
               Whether the editor should remove trailing blanks when
               saving a file.

         Line terminator
               Choose between Unix, Windows and Unchanged line
               terminators when saving files. Choosing Unchanged will
               use the original line terminator when saving the file;
               Unix will use LF line terminators; Windows will use CRLF
               line terminators.

         Display line numbers
               Whether the line numbers should be displayed in file
               editors.

         Tooltips
               Whether tool tips should be displayed automatically.

         Highlight delimiters
               Whether matching delimiters should be highlighting. The
               list of delimiters include: `{}[]()'

         Autosave delay
               The period (in seconds) after which a source editor is
               automatically saved.  0 if none.

               Each modified file is saved under a file called
               `.#filename', which is removed on the next explicit save
               operation.

         Column highlight
               The column number to highlight and draw in the editors.
               0 if none.

         External editor
               The default external editor to use.

         Custom editor command
               Specify the command line for launching a custom editor.
               It is assumed that the command will create a new
               window/terminal as needed.  If the editor itself does
               not provide this capability (such as vi or pico), you
               can use an external terminal command, e.g:

                    xterm -geometry 80x50 -exec vi +%l %f

               The following substitutions are provided:
              `%l'
                    line to display

              `%c'
                    column to display

              `%f'
                    full pathname of file to edit

              `%e'
                    extended lisp command

              `%p'
                    top level project file name

              `%%'
                    percent sign ('%')

         Always use external editor
               True if all editions should be done with the external
               editor. This will deactivate completely the internal
               editor. False if the external editor needs to be
               explicitly called by the user.

    Fonts & Colors

         Keywords
               Font and colors used to highlight keywords.

         Current line color
               Color for highlighting the current line. Leave it to
               blank for no highlighting.  Setting the color to white
               will set a transparent color.

         Current block color
               Color for highlighting the current source block. Setting
               the color to white will disable the block highlighting
               (recommended on slow machines).

         Comments
               Font and colors used to highlight comments.  Setting the
               color to white will set a transparent color.

         Strings
               Font and colors used to highlight strings.  Setting the
               color to white will set a transparent color.

         Line highlighting color
               Color for highlighting lines.

         Default font
               The font used in the source editor.

    Ada

         Auto indentation
               How the editor should indent Ada sources.  None means no
               indentation; Simple means that indentation from the
               previous line is used for the next line; Extended means
               that a language specific parser is used for indenting
               sources.

         Use tabulations
               Whether the editor should use tabulations when indenting.

         Default indentation
               The number of spaces for the default Ada indentation.

         Continuation lines
               The number of extra spaces for continuation lines.

         Declaration lines
               The number of extra spaces for multiple line
               declarations.  For example, using a value of 4, here is
               how the following code would be indented:

                    variable1,
                        variable2,
                        variable3 : Integer;

         RM style case indentation
               Whether GPS should indent case statements with an extra
               level, as used in the Ada Reference Manual, e.g:

                    case Value is
                       when others =>
                          null;
                    end case;

               If this preference is set to `False', this would be
               indented as:

                    case Value is
                    when others =>
                       null;
                    end case;

    C/C++

         Auto indentation
               How the editor should indent C/C++ sources.  None means
               no indentation; Simple means that indentation from the
               previous line is used for the next line; Extended means
               that a language specific parser is used for indenting
               sources.

         Use tabulations
               Whether the editor should use tabulations when
               indenting. If True, the editor will replace each
               occurrence of eight characters by a tabulation character.

         Default indentation
               The number of spaces for the default indentation.

    Keys

         Auto-indentation
               Key used for auto-indenting lines or block of lines.

         Completion
               Key used for automatic completion of identifiers.

         Jump to delimiter
               Key used for moving the cursor to the corresponding
               delimiter.  Delimiters include parentheses, brackets,
               and braces.

   * Debugger
    General

         Color highlighting
               Color used for highlighting in the debugger console.

         Break on exceptions
               Specifies whether a breakpoint on all exceptions should
               be set by default when loading a program.

         Execution window
               Whether the debugger should create a separate execution
               window for the program debugged.  If true, a separate
               console will be created. Under Unix systems, this
               console is another window in the bottom part of the main
               window; under Windows, this is a separate window created
               by the underlying gdb, since Windows does not have the
               notion of separate terminals (aka ttys).

               Note that in this mode under Windows, the
               `Debug->Interrupt' menu will not interrupt the debugged
               program. Instead, you need to hit <Ctrl-C> in the
               separate execution window to interrupt it while it is
               running.

               If false, no execution window will be created. The
               debugger assumes that the program being debugged does
               not require input, or that if it does, input is handled
               outside GPS. For example, when you attach to a running
               process, this process already has a separate associated
               terminal.

         Show lines with code
               Specifies whether blue dots should be displayed in the
               source editor for lines that contain code. If set to
               False, gray dots will be displayed instead on each line,
               allowing breakpoint on any line. Disabling this option
               provides a faster feedback, since GPS does not need to
               query the debugger about which lines contain code.

    Assembly

         Current assembly line
               Color used to highlight the assembly code for the
               current line.

         Range size
               Number of assembly lines to display in the initial
               display of the assembly window. If the size is 0, then
               the whole subprogram is displayed, but this can take a
               very long time on slow machines.

    Data
          Lets you change the preferences of the Data Window, in
          particular the fonts and colors used to display the data
          graphically.

         Clickable item
               Indicates color to be used for the items that are
               click-able (e.g pointers).

         Changed data
               Indicates color to be used to highlight fields that have
               changed since the last update.

         Item name
               Indicates font to be used for the name of the item.

         Item type
               Indicates font to be used to display the type of the
               item.

         Detect aliases
               If enabled, do not create new items when an item with
               the same address is already present on the canvas.

    Memory

         Default color
               Color used by default in the memory view window.

         Color highlighting
               Color used for highlighted items.

         Selection
               Color used for selected items.

   * Helpers
    List processes
          Command used to list processes running on the machine.

    Remote shell
          Program used to run a process on a remote machine. You can
          specify arguments, e.g. `rsh -l user'

    Remote copy
          Program used to copy a file from a remote machine. You can
          specify arguments, e.g. `rcp -l user'

    Execute command
          Program used to execute commands externally.

    Print command
          Program used to print files. By default `a2ps', available
          under GNU/Linux systems. This utility can be used on most
          Unix systems, and can be downloaded from
          <http://www.inf.enst.fr/~demaille/a2ps>

          Under Windows systems, a possible replacement is the
          PrintFile freeware utility which is available from
          <http://www.lerup.com/printfile/descr.html>

   * Browsers
    General

         Selected item color
               Color to use to draw the selected item.

         Background color
               Color used to draw the background of the browsers.

         Hyper link color
               Color used to draw the hyper links in the items.

         Selected link color
               Color to use for links between selected items.

         Default link color
               Color used to draw the links between unselected items.

         Ancestor items color
               Color to use for the background of the items linked to
               the selected item.

         Offspring items color
               Color to use for the background of the items linked from
               the selected item.

         Vertical layout
               Whether the layout of the graph should be vertical
               (True) or horizontal (False).

    File Dependencies

         Show system files
               Whether the system files (Ada runtime or standard C
               include files) should be visible in the browser.

         Show implicit dependencies
               If False, then only the explicit dependencies are shown
               in the browser.  Otherwise, all dependencies, even
               implicit, are displayed.

   * Visual diff
    Context length
          The number of lines displayed before and after each chunk of
          differences.  Specifying -1 will display the whole file.

    Diff command
          Command used to compute differences between two files.
          Arguments can also be specified. The visual diff expects a
          standard diff output with no context (that is, no `-c' nor
          `-u' switch).  Arguments of interest may include (this will
          depend on the version of diff used):

         -b
               Ignore changes in amount of white space.

         -B
               Ignore changes that just insert or delete blank lines.

         -i
               Ignore changes in case; consider upper and lower case
               letters equivalent.

         -w
               Ignore white space when comparing lines.

    Patch command
          Command used to apply a patch. Arguments can also be
          specified.

   * Messages
    Color highlighting
          Color used to highlight text in the messages window.

    Color highlighting
          Color used to highlight lines causing compilation
          errors/warnings in the source editors. When this color is set
          to white, the errors/warnings are not highlighted. (*Note
          Compilation/Build::)

    Show build progress
          Whether the progress bar should show progress during builds.

    File pattern
          Pattern used to detect file locations from the messages
          window.  This is particularly useful when using an external
          tool such as a compiler or a search tool, so that GPS will
          highlight and allow navigation through source locations. This
          is a standard system V regular expression containing two or
          three parenthesized subexpressions corresponding to the file,
          line and column patterns.

    File index
          Index of filename in the file pattern.

    Line index
          Index of the line number in the file pattern.

    Column index
          Index of the column number in the file pattern.

   * Project
    Relative paths
          Whether paths should be absolute or relative when the
          projects are modified.


Customizing the Menu and Tool Bar
=================================

You can customize the GPS menu bar in two different ways: you can
redefine or add new key bindings to the existing menu items, and you
can define new menu items.

Redefining key bindings
-----------------------

In order to define or redefine key bindings, you first need to enable
the dynamic key binding feature in the Preferences dialog.  *Note
Dynamic key bindings::.

   Then, you can simply navigate through the menus, and type the key
binding you want to associate to a particular item. To remove a key
binding, use the <Backspace> key.  Your changes will be saved when GPS
exits, in a file called `$HOME/.gps/custom_keys'. In particular, this
means that if for some reason you need to edit the file manually, you
need to do it outside of GPS, or save the file under a different name,
and rename it after exiting GPS.

Adding menu items
-----------------

The GPS menu bar can be customized through an XML file put under the
directory `$HOME/.gps/customize' on Unix systems, and
`%HOME%\.gps\customize' on Windows systems.  Any file in the
`customize' directory will be loaded by GPS at start up. Alternatively,
you can also put system wide customization files under the directory
`<INSTALL>/share/gps/customize', where `<INSTALL>' is the name of the
GPS installation directory.

   Here is an example for such a file:


     <?xml version="1.0"?>
     <Custom>
       <Submenu>
         <Title>custom menu</Title>
         <Menu_Item>
         <Title>item 1</Title>
           <Action>external-command 1</Action>
         </Menu_Item>
     
         <Submenu>
           <Title>other menu</Title>
           <Menu_Item>
             <Title> (etc..)
           </Menu_Item>
     
           <Submenu>
             (...)
           </Submenu>
         </Submenu>
       </Submenu>
     </Custom>

   The example above creates a top-level menu named `custom menu'.
This menu contains a menu item named `item 1', which is associated to
the shell command `external-command 1', a sub menu named `other menu',
etc...

   Note for Windows users: like under UNIX, scripts can be called from
custom menu. In order to do that, you must write your script in a
`.bat' or `.cmd' file, and call this file using `cmd /c'.  Thus, the
`Action' tag would look like:

     <Action>cmd /c c:\.gps\my_scripts\my_command.cmd</Action>

   As well as external commands, you can use custom menu items to
invoke GPS commands using the `GPS_Action' tag. The following example
shows how to create a menu to invoke the `help' interactive command and
to open the file `main.c'.

     <Submenu>
       <Title>Edit</Title>
       <Menu_Item>
         <Title>List GPS commands</Title>
         <GPS_Action>help</GPS_Action>
       </Menu_Item>
       <Menu_Item>
         <Title>Edit main.c</Title>
         <GPS_Action>edit main.c</GPS_Action>
       </Menu_Item>
     </Submenu>

   See below for more information on this `GPS_Action' tag.

   You can define the accelerator keys for your menus, using underscores
in the titles. Thus, if you want an accelerator on the first letter in
a menu named `File', set its title as `_File'.

   You can add items or sub menus to existing menus, using titles for
menus that already exist. For example, this adds an item named `Robert'
to the `Edit' menu.


     <Submenu>
       <Title>Edit</Title>
       <Menu_Item>
         <Title>Robert</Title>
       </Menu_Item>
     </Submenu>

   Use the `/' separator to identify the sub menu in a menu. For
example, this adds a sub menu named `Olga' containing an item named
`Item' to the `Edit' menu.


     <Submenu>
       <Title>Edit/Olga</Title>
       <Menu_Item>
         <Title>Item</Title>
       </Menu_Item>
     </Submenu>

   Adding an item with an empty title or no title at all inserts a menu
separator.

   The following tags are available in a `Submenu' section:

`Title'
     Found inside a `Submenu' or `Menu_Item': set title of the submenu
     or menu item.

`Menu_Item'
     A menu item inside a submenu.

`Action'
     External command associated with a menu item.

`GPS_Action'
     GPS specific command associated with a menu item. This is a command
     written in one of the shell scripts supported by GPS. You can
     specify the language as an attribute of the XML node. The name of
     the attribute is `lang'. The default value for this attribute is
     `shell', i.e. the command is written with the GPS shell.

     When programming with the GPS shell, you can execute multiple
     commands by separating them with semicolons. Therefore, the
     following example adds a menu which lists all the files used by
     the current file, in a project browser. Note: due to some current
     limitation of the parsing of the custom files, the '%' argument
     must be surrounded by spaces, as shown in the example.

          <Menu_Item>
            <Title>Current file uses</Title>
            <GPS_Action lang="shell">File %f ; File.uses $1</GPS_Action>
          </Menu_Item>

     It is possible to mix both shell commands and external commands.
     For instance, the following command opens an xterm (on Unix
     systems only) in the current directory, which depends on the
     context.

          <Menu_Item>
            <Title>_Xterm in current directory</Title>
            <GPS_Action lang="shell">cd %d</GPS_Action>
            <Action>xterm</Action>
          </Menu_Item>

Adding tool bar buttons
-----------------------

As an alternative to creating new menu items, you can create new
buttons on the tool bar, with exactly the same syntax, by using the
`<Toolbar_Item>' tag in place of the `<Submenu>' tag.  Within this tag,
the tag `<Pixmap>' can be used to indicate the location of an image
file (of the type `jpeg, png, gif' or `xpm') to be used as icon for the
button. An empty `<Toolbar_Item>' tag indicates a separator in the tool
bar.


     <Toolbar_Item>
       <Title>Custom Button</Title>
       <Pixmap>/my_pixmaps/button.jpg</Pixmap>
       <GPS_Action>my gps command</GPS_Action>
     </Toolbar_Item>

   The following tags are available in a `Toolbar_Item' section:

`Title'
     Name of the custom button.

`Pixmap'
     Pixmap file associated with the tool bar button.

`Action'
     External command associated with a tool bar button.

`GPS_Action'
     GPS specific command associated with a tool bar button.

Macro arguments
---------------

When using an `Action' node in a menu or tool bar item, you can use
macro arguments to pass to your shell commands. Macro arguments are
special parameters that are transformed every time the command is
executed.  The following macro arguments are provided:

`%f'
     Base name of the currently opened file.

`%F'
     Absolute name of the currently opened file.

`%p'
     The current project. This is the name of the project, not the
     project file.

`%pp'
     The current project file pathname.

`%PP'
     The root project pathname.

`%(p|P)[r](d|s)[f]'
     Substituted by the list of sources or directories of a given
     project:

    `P'
          the root project.

    `p'
          the selected project, or the root project if there is no
          project selected.

    `r'
          recurse through the projects: sub projects will be listed as
          well as their sub projects, etc...

    `d'
          list the source directories.

    `s'
          list the source files.

    `f'
          output the list into a file and substitute the parameter with
          the name of that file.

   Examples:

`%Ps'
     Replaced by a list of source files in the root project.

`%prs'
     Replaced by a list of files in the current project, and all
     imported sub projects, recursively.

`%prdf'
     Replaced by the name of a file that contains a list of source
     directories in the current project, and all imported sub projects,
     recursively.

Adding Support for New Languages
================================

You can define new languages in a custom file by using the `Language'
tag. Defining languages gives GPS the ability to highlight the syntax
of a file, explore a file (using e.g. the project explorer), and find
files associated with a given language.

   As described previously for menu items, any file in the `customize'
directory will be loaded by GPS at start up.

   The following tags are available in a `Language' section:

`Name'
     A short string describing the name of the language.

`Spec_Suffix'
     A string describing the suffix of spec/definition files for this
     language.  If the language does not have the notion of spec or
     definition file, you can ignore this value.

`Body_Suffix'
     A string describing the suffix of body/implementation files for
     this language.

`Keywords'
     A V7 style regular expression for recognizing and highlighting
     keywords.  Multiple `Keywords' tags can be specified, and will be
     concatenated into a single regular expression.

     The full grammar of the regular expression can be found in the
     spec of the file `g-regpat.ads' in the GNAT run time.

`Context'
     Describes the context used to highlight the syntax of a file.

    `Comment_Start'
          A string defining the beginning of a multiple-line comment.

    `Comment_End'
          A string defining the end of a multiple-line comment.

    `New_Line_Comment_Start'
          A string defining the beginning of a single line comment
          (ended at the next    end of line).

    `String_Delimiter'
          A character defining the string delimiter.

    `Quote_Character'
          A character defining the quote character, used for e.g.
          canceling the    meaning of a string delimiter (`\' in C).

    `Constant_Character'
          A character defining the beginning of a character literal.

    `Can_Indent'
          A boolean indicating whether indentation should be enabled
          for this    language. The indentation mechanism used will be
          the same for all languages:    the number of spaces at the
          beginning of the current line is used when    indenting the
          next line.

    `Syntax_Highlighting'
          A boolean indicating whether the syntax should be
          highlighted/colorized.

    `Case_Sensitive'
          A boolean indicating whether the language (and in particular
          the identifiers    and keywords) is case sensitive.

`Categories'
     Optional node to describe the categories supported by the project
     explorer for the current language. This node contains a list of
     `Category' nodes, each describing the characteristics of a given
     category, with the following nodes:

    `Name'
          Name of the category, which can be one of:    package,
          namespace, procedure, function, task, method, constructor,
          destructor, protected, entry,    class, structure, union,
          type, subtype, variable, local_variable,
          representation_clause,    with, use, include,
          loop_statement, case_statement, if_statement,
          select_statement,    accept_statement, declare_block,
          simple_block, exception_handler.

    `Pattern'
          Regular expression used to detect a language category.     As
          for the `Keywords' node, multiple `Pattern' tags can be
          specified and will be concatenated into a single regular
          expression.

    `Index'
          Index in the pattern used to extract the name of the entity
          contained in    this category.

Here is an example of a language definition for the GPS project files:

     <?xml version="1.0"?>
     <Custom>
       <Language>
         <Name>Project File</Name>
         <Spec_Suffix>.gpr</Spec_Suffix>
     
         <Keywords>^(case|e(nd|xte(nds|rnal))|for|is|</Keywords>
         <Keywords>limited|null|others|</Keywords>
         <Keywords>p(ackage|roject)|renames|type|use|w(hen|ith))\b</Keywords>
     
         <Context>
           <New_Line_Comment_Start>--</New_Line_Comment_Start>
           <String_Delimiter>"</String_Delimiter>
           <Constant_Character>'</Constant_Character>
           <Can_Indent>True</Can_Indent>
           <Syntax_Highlighting>True</Syntax_Highlighting>
           <Case_Sensitive>False</Case_Sensitive>
         </Context>
     
         <Categories>
           <Category>
             <Name>package</Name>
             <Pattern>^[ \t]*package[ \t]+((\w|\.)+)</Pattern>
             <Index>1</Index>
           </Category>
           <Category>
             <Name>type</Name>
             <Pattern>^[ \t]*type[ \t]+(\w+)</Pattern>
             <Index>1</Index>
           </Category>
         </Categories>
       </Language>
     </Custom>

Defining Text Aliases
=====================

GPS provides a mechanism known as aliases. These are defined through
the menu `Edit->Aliases'. Each alias has a name, which is generally a
short string of characters. When you type them in any textual entry in
GPS (generally a source editor, but also entry fields for instance in
the file selector), and then press the special activation key (by
default <control-o>, controlled by a preference), this name is removed
from the source editor, and replaced by the text you have associated
with it.

   Alias names may be composed of any character, but must start with a
letter. GPS will jump to the start of each word before the current
cursor position, and if the characters between this word start and the
cursor position is an alias name, this alias is expanded.

   The alias editor is divided into three main parts: on the left side,
the list of currently defined aliases is shown. Clicking on any of them
will display the replacement text for this alias. If you click again the
selected alias, GPS displays a text entry which you can use to rename
an existing alias. Alias names must start with a letter. A check button
at the bottom selects whether the read-only aliases (i.e. system-wide
aliases) should be displayed.

   The second part is the expansion text for the alias, at the bottom
right corner. This replacement text can used multiple lines, and
contain some special text that act as a special replacement. These
special texts are highlighted in a different color. You can insert
these special entities either by typing them, or by right-clicking in
the editor, and select the entity in the contextual menu.

   The following special entities are currently defined:

`%_'
     This is the position where the cursor should be put once the
     replacement text has been inserted in the editor.

`%(name)'
     This is the name of a parameter. name can be any string you want,
     excluding closing parenthesis. See below for more information on
     parameters.

`%D'
     This is the current date, in ISO format. The year is displayed
     first, then the month and the day

`%H'
     This is the current time (hour, minutes and seconds)

`%l'
     If the expansion of the alias is done in a source editor, this is
     the line on which the cursor is when pressing <control-o>.

`%c'
     This is similar to %l, except it returns the current column.

`%f'
     If the expansion is done in a source editor, this is the name of
     the current file (its base name only, this doesn't include the
     directory)

`%d'
     If the expansion is done in a source editor, this is the directory
     in which the current file is

`%p'
     If the expansion is done in a source editor, this is the base name
     of the project file to which the file belongs.

`%P'
     If the expansion is done in a source editor, this is the full path
     name to the project file (directory and base name).

   The indentation as set in the expansion of the alias is preserved
when the alias is expanded. All the lines will be indented the same
amount to the right as the alias name.

   The third part of the aliases editor, at the top right corner, lists
the parameters for the currently selected alias. Any time you insert a
%(name) string in the expansion text, GPS automatically detects there
is a new parameter reference (or an old reference has changed name or
was removed); the list of parameters is automatically updated to show
the current list.

   Each parameters has three attributes:

name
     This is the name you use in the expansion text of the alias in the
     %(name) special entity.

Environment
     This specifies whether the default value of the parameter comes
     from the list of environment variables set before GPS was started.

default value
     Instead of getting the default value from the environment variable,
     you can also specify a fixed text.  Clicking on the initial value
     of the currently selected variable opens a text entry which you
     can use to edit this default value.

   When an alias that contains parameters is expanded, GPS will first
display a dialog to ask for the value of the parameters. You can
interactively enter this value, which replaces all the %(name) entities
in the expansion text.

Aliases files
-------------

GPS manages multiple aliases files. One of them is editable
interactively by the user through the `Edit->Aliases' menu, whereas all
the others are defined system-wide, and are not editable interactively.

   The user-defined file is `$HOME/.gps/aliases'.

   The system files are all the files stored in the directory
`<prefix>/share/gps/aliases', where `<prefix>' is the path in which GPS
was installed. The aliases defined in these files are read-only, and
indicated as such in the aliases editor.

   All the files have the same XML format, which can be seen in the
following example. Each alias has its own <alias> tag.

     <?xml version="1.0"?>
     <Aliases>
       <alias name="proc" >
         <param name="p" >Proc1</param>
         <param environment="true" name="env" />
         <text>procedure %(p) is
     %(env)%_
     end %(p);</text>
       </alias>
     </Aliases>

   The following tags are available:

`alias'
     This indicates the start of a new alias. It has one mandatory
     attribute, `name', which the text to type in the source editor
     before pressing <control-o>.

`param'
     These are children of the `alias' node. There is one per parameter
     of the alias. They have one mandatory attribute, `name', which is
     the name to type between %(name) in the alias expansion text.

     They have one optional attribute, `environment', which indicates
     the default value must be read from the environment variables if
     it is set to true.

     These tags contain text, which is the default value for the
     parameter.

`text'
     This is a child of the `alias' node, whose value is the
     replacement text for the alias.

Defining New Styles and Key Bindings
====================================

In addition to the preferences dialog, GPS can be configured through the
Gtk+ mechanism of `RC files'. You can create a text file called `gtkrc'
in the gps home directory (`~/.gps' on Unix systems), or as a global
change, in the directory etc/gps in the GPS installation.

   This file follows the Gtk+ resource file syntax and gives the
possibility in particular to define a number of styles and key bindings
and attach them to particular visual objects such as text editors, menu
items, ...

   For example, you can set <Ctrl-v> in the source editors to scroll
forward one page. The following code defines this new key binding:


     # Create new key bindings for text editors
     binding "custom-text-key"
     {
        # define Ctrl-v to scroll forward one page
        bind "<ctrl>v" { "move-cursor" (pages, 1, 0) }
     }
     
     # Associate the new binding created above with text editors
     class "GtkTextView" binding "custom-text-key"

Toplevel declarations
---------------------

An RC file is a text file which is composed of a sequence of
declarations.  All the literals are case sensitive; `#' characters
delimit comments and the portion of a line after a `#' is ignored when
parsing an RC file.  The syntax of the top-level declarations is
described below.  Opening/closing brackets on the same line ({ ... })
are used to represent a sequence of 0 or more elements. Brackets on
their own line are real bracket characters.

     toplevel-declarations ::=
        { declaration }
     
     declaration ::=
        include-file | pixmap-path | style-definition | binding-definition |
        enable-resource
     
     include-file ::=
        include string_literal
     
     pixmap-path ::=
        pixmap_path string_literal
     
     style-definition ::=
        style resource-name [ = parent ]
        {
           sequence-of-style
        }
     
     binding-definition ::=
        binding resource-name
        {
           sequence-of-binding
        }
     
     enable-resource ::=
        class "widget-name" (binding | style) resource-name
     
     resource-name ::=
        string_literal

The table below describes the meaning of each of these toplevel
declarations:

`include filename'
     Parses another file at this point. If filename is not an absolute
     filename, it is searched in the directories of the currently open
     RC file.

`pixmap_path path'
     Sets a path (a list of directories separated by colons) that will
     be searched for pixmaps referenced in RC files.

`style name [ = parent ] { ... }'
     Declares a style. If parent is specified, name inherits its
     default attributes from parent. You can specify "default" to
     designate the default style, e.g:

          style "my-style" = "default" { ... }

     See *Note Defining new styles:: for more details.

`binding name { ... }'
     Declares a binding set.  See *Note Defining new key bindings:: for
     more details.

`class widget-name (binding | style) name'
     Specifies a binding or style set for a particular set of visual
     objects.

`resource-name'
     An arbitrary user defined name.

Defining new styles
-------------------

A RC style is specified by a style declaration in a RC file, and then
bound to visual objects with a class declaration.  Within each type of
declaration, later declarations override earlier ones.

   For example, the following code will change the background color of
any button, when it is pressed. It will also set a background pixmap
when it is not pressed. The style also inherits from the one above, so
that the buttons also use the default font.


     pixmap_path "directory_that_contains_the_pixmap"
     style "custom-button" = "default"
     {
       bg_pixmap[NORMAL]="pixmap_file"
       bg[ACTIVE]="blue"
     }
     class "GtkButton" style "custom-button"

Here is the syntax for defining styles:


     sequence-of-style ::=
        { style | property }
     
     style ::=
        style-name[state] = string_literal
     
     style-name ::=
        bg | fg | base | text | bg_pixmap | font_name
     
     state ::=
        NORMAL | ACTIVE | PRELIGHT | SELECTED | INSENSITIVE
     
     property ::=
        widget-name::widget-property = value
     
     widget-property ::=
        cursor-aspect-ratio | cursor-color

The table below describes the meaning of each of these elements:

`bg[state] = color'
     Sets the color used for the background of most visual objects.

`fg[state] = color'
     Sets the color used for the foreground of most visual objects.

`base[state] = color'
     Sets the color used for the background of visual objects
     displaying editable text, for instance the text editor in GPS.

`text[state] = color'
     Sets the color used for foreground of visual objects using base
     for the background color.

`bg_pixmap[state] = pixmap'
     Sets a background pixmap to be used in place of the bg color. The
     special value "<parent>" may be used to indicate that the visual
     object should use the same background pixmap as its parent. The
     special value "<none>" may be used to indicate no background
     pixmap.

`font_name = font'
     Sets the font for a visual object.  Font is a font name as listed
     in the font selector in the preferences dialog, e.g. "Sans Italic
     10".

`GtkTextView::cursor-aspect-ratio = value'
     Width ratio with which to draw the insertion cursor. Value is a
     float value between 0.0 and 1.0. The default value is 0.04.

`GtkTextView::cursor-color = color'
     Color with which to draw insertion cursor

The colors and background pixmaps are specified as a function of the
state of the visual object. The states are:

`NORMAL'
     A color used for a visual object in its normal state.

`ACTIVE'
     A variant of the NORMAL color used when the visual object is in
     the active state, and also for the trough of a ScrollBar, tabs of a
     NoteBook other than the current tab and similar areas. Frequently,
     this should be a darker variant of the NORMAL color.

`PRELIGHT'
     A color used for visual objects in the PRELIGHT state. This state
     is used for Buttons and MenuItems that have the mouse cursor over
     them, and for their children.

`SELECTED'
     A color used to highlight data selected by the user. For instance,
     the selected items in a list object, and the selection in an
     editable object.

`INSENSITIVE'
     A color used for the background of visual objects that have been
     set insensitive.

   Colors can be specified as a string containing a color name (under
Unix systems, GTK+ knows all names from the X color database
/usr/lib/X11/rgb.txt), in one of the hexadecimal forms `#rrrrggggbbbb',
`#rrrgggbbb', `#rrggbb', or `#rgb', where r, g and b are hex digits, or
they can be specified as a triplet `{r, g, b}', where r, g and b are
either integers in the range 0-65535 or floats in the range 0.0-1.0.

Defining new key bindings
-------------------------

Key bindings allow you to specify actions to be taken on a given key
press. The syntax to define new key bindings is described below.


     sequence-of-binding ::=
        { binding }
     
     binding ::=
        bind "key-name"
        {
           sequence-of-commands
        }
     
     sequence-of-commands ::=
        { command }
     
     command ::=
        "command-kind" (parameters)
     
     parameters ::=
        [first-parameter {, number}]
     
     widget-name ::=
        GtkButton | GtkDialog | GtkEntry | GtkMenuItem |
        GtkMenuShell | GtkTextView | GtkTreeView
     
     command-kind ::=
        move-cursor | page-horizontally | set-anchor | insert-at-cursor |
        delete-from-cursor | cut-clipboard | copy-clipboard | paste-clipboard |
        toggle-overwrite | move-focus | activate | select-all | unselect-all |
        select-cursor-row | toggle-cursor-row | expand-collapse-cursor-row |
        select-cursor-parent | start-interactive-search | clicked | close |
        move-current
     
     first-parameter ::=
        movement-step | count | extend-selection | delete-type | start-editing |
        logical | expand | expand-all | menu-direction | string_litteral
     
     number ::=
        [-|+]digit{digit}
     
     key-name ::=
        {modifier}key
     
     modifier ::=
        <ctrl> | <alt> | <shift>
     
     key ::=
        letter | digit |
        BackSpace | Tab | Return | Pause | Scroll_Lock | Sys_Req | Escape |
        Delete | Home | Left | Up | Right | Down | Page_Up | Page_Down | End |
        Insert | Break | Num_Lock |
        F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F10 | F11 | F12 |
        Caps_Lock | space | exclam | quotedbl | numbersign | dollar | percent |
        ampersand | apostrophe | quoteright | parenleft | parenright | asterisk |
        plus | comma | minus | period | slash | colon | semicolon | less |
        equal | greater | question | at | bracketleft | backslash |
        bracketright | underscore | grave | quoteleft | braceleft | bar |
        braceright

The list of valid `command-kind' values and their parameters depend on
the widget name:

`GtkButton'
     Applies to buttons.
    `clicked ()'
          Generate a button click event.

`GtkDialog'
     Applies to dialog windows.
    `close ()'
          Close the current dialog box.

`GtkEntry'
     Applies to single line text entries.
    `activate ()'
          Activate the text entry.

    `move-cursor (movement-step, count, extend-selection)'
          Move insertion point by count steps. If extend-selection is
          true,       create or extend the selection.

    `insert-at-cursor (string)'
          Insert a given text string at the cursor.

    `delete-from-cursor (delete-type, count)'
          Delete count units from the cursor.

    `cut-clipboard ()'
          Cut the current selection to the clipboard.

    `copy-clipboard ()'
          Copy the current selection to the clipboard.

    `paste-clipboard ()'
          Paste the contents of the clipboard.

    `toggle-overwrite ()'
          Toggle the current overwrite mode.

`GtkMenuItem'
     Applies to menu items.
    `activate ()'
          Activate the menu item.

`GtkMenuShell'
     Applies to menus.
    `move-current (menu-direction)'
          Move the current menu entry to the given direction.

`GtkTextView'
     Applies to source and text editors.
    `move-cursor (movement-step, count, extend-selection)'
          Move insertion point by count steps. If extend-selection is
          true,       create or extend the selection.

    `page-horizontally (count, extend-selection)'
          Move cursor to the beginning (count=-1) or the end (count=1)
          of the       current line.

    `set-anchor ()'
          Move the anchor to the cursor position.

    `insert-at-cursor (string)'
          Insert a given text string at the cursor.

    `delete-from-cursor (delete-type, count)'
          Delete count units from the cursor.

    `cut-clipboard ()'
          Cut the current selection to the clipboard.

    `copy-clipboard ()'
          Copy the current selection to the clipboard.

    `paste-clipboard ()'
          Paste the contents of the clipboard.

    `toggle-overwrite ()'
          Toggle the current overwrite mode.

`GtkTreeView'
     Applies to tree and list objects, in particular the Location Tree,
     the    Project View, the File View and the VCS Explorer.
    `move-cursor (movement-step, count)'
          Move insertion point.

    `select-all ()'
          Select all rows.

    `unselect-all ()'
          Unselect all rows.

    `select-cursor-row (start-editing)'
          Select or unselect the current row.

    `toggle-cursor-row ()'
          Toggle the selection of the current row.

    `expand-collapse-cursor-row (logical, expand, expand-all)'
          Expand (expand=1) or collapse (expand=0) the current row.
            If expand-all=1, also expand all children recursively.
            Parameter logical currently ignored.

    `select-cursor-parent ()'
          Select the parent row of the current selection.

    `start-interactive-search ()'
          Start interactive search on the tree view. This will open a
          small window       at the bottom of the tree view where you
          can interactively type names.        The first matching name
          in the tree will be selected while you type it.        You
          can then also use the <up> and <down> keys to navigate through
               all the items matching the current text.

The possible values of the parameters listed above are:

`count'
     Signed integer value.

`string'
     Quoted string, e.g "text".

`extend-selection, start-editing, logical, expand, expand-all:'
     Boolean value. 0 means false, 1 means true.

`delete-type'

    `chars'
          Delete a given amount of characters.

    `word-ends'
          Delete only the portion of the word to the left/right of
          cursor if we're       in the middle of a word.

    `paragraph-ends'
          Delete between cursor and the end (count=1) or beginning
          (count=-1) of       current line.

    `paragraphs'
          Delete whole line.

    `whitespace'
          Delete all white spaces around the cursor.

`menu-direction'

    `parent'
          Select the parent menu item.

    `child'
          Select the first child menu item.

    `next'
          Select the next (sibling) menu item.

    `prev'
          Select the previous (sibling) menu item.

`movement-step'

    `logical-positions'
          Move by forward/back graphemes.

    `visual-positions'
          Move by left/right graphemes.

    `words'
          Move by forward/back words.

    `display-lines'
          Move up/down lines (wrapped lines).

    `display-line-ends'
          Move to either end of a line (wrapped lines).

    `paragraphs'
          Move up/down paragraphs (newline-ended lines).

    `paragraph-ends'
          Move to either end of a paragraph.

    `pages'
          Move by pages.

    `buffer-ends'
          Move to the end (count=1) or to the beginning (count=-1) of
          the file.

Scripting GPS
=============

Scripts
-------

Scripts are small programs that interact with GPS and allow you to
perform complex tasks repetitively and easily. GPS includes support for
two scripting languages currently, although additional languages might
be added in the future. These two languages are described in the
following section.

   Support for scripting is currently work in progress in GPS. As a
result, not many commands are currently exported by GPS, although their
number is increasing daily. These commands are similar to what is
available to people who extend GPS directly in Ada, but with a strong
advantage: they do not require any recompilation of the GPS core, and
can be tested and executed interactively.

   The goal of such scripts is to be able to help automate processes
such as builds, automatic generation of graphs,...

   All the scripting languages share the same set of commands exported
by GPS, thanks to a abstract interface defined in the GPS core. As a
result, GPS modules do not have to be modified when new scripting
languages are added.

   Scripts can be executed immediately upon startup of GPS by using the
command line switch `--load'. Specifying the following command line:

     gps --load=shell:mytest.gps

   will force the gps script `mytest.gps' to be executed immediately,
before GPS starts reacting to user's requests. This is useful if you
want to do some special initializations of the environment. It can also
be used as a command line interface to GPS, if you script's last
command is to exit GPS.

   In line commands can also be given directly on the command line
through `--eval' command line switch.

   For instance, if you want to analyze an entity in the entity browser
from the command line, you would pass the following command switches:

     gps --eval=shell:'Entity entity_name file_name; Entity.show %1'

The GPS Shell
-------------

The GPS shell is a very simple-minded, line-oriented language. It is
accessible through the `Shell' window at the bottom of the GPS window.
It is similar to a Unix shell, or a command window on Windows systems.

   Type `help' at the prompt to get the list of available commands, or
`help' followed by the name of a command to get more information on
that specific command.

   The following example shows how to get some information on a source
entity, and find all references to this entity in the application. It
searches for the entity "entity_name", which has at least one reference
anywhere in the file "file_name.adb". After the first command, GPS
returns an identifier for this entity, which can be used for all
commands that need an entity as a parameter, as is the case for the
second command. When run, the second command will automatically display
all matching references in the location window.

     GPS> Entity my_entity file_name.adb
     <Entity_0x09055790>
     GPS> Entity.find_all_refs <Entity_0x09055790>

   Since the GPS shell is very simple, it doesn't provide any reference
counting for the result types. As a result, all the values returned by
a command, such as `<Entity_0x09055790>' in the example above, are kept
in memory.

   The GPS shell provides the command `clear_cache' which removes all
such values from the memory. After this command is run, you can no
longer use references obtained from previous commands, although of
course you can run these commands again to get a new reference.

   The return value of the 9 previous commands can easily be recalled by
passing `%1', `%2',... on the command line. For instance, the previous
example could be rewritten as

     GPS> Entity my_entity file_name.adb
     <Entity_0x09055790>
     GPS> Entity.find_all_refs %1

   These return values will be modified also for internal commands sent
by GPS, so you should really only use this when you emit multiple
commands at the same time, and don't do any other action in GPS. This
is mostly useful when used for command-line scripts (see `--eval' and
`--load'), or for custom files, *Note Customizing the Menu and Tool
Bar::.

   In future versions of GPS, it will be possible to use more advanced
scripting languages such as `Python'.

Environment
***********

Command Line Options
====================

     Usage:
        gps [options] [-Pproject-file] [source1] [source2] ...
     Options:
        --help              Show this help message and exit
        --version           Show the GPS version and exit
        --debug[=program]   Start a debug session and optionally load the
                            program with the given arguments
        --debugger debugger Specify the debugger's command line
        --target=TARG:PRO   Load program on machine TARG using protocol PRO
        --load=lang:file    Execute an external file written in the language lang
        --eval=lang:file    Execute an in-line script written in the language lang
     
     Source files are searched everywhere on the project's source path

Environment Variables
=====================

The following environment variables can be set to override some default
settings in GPS:

`GPS_ROOT'
     Override the default root directory specified when GPS is built
     (during the configure process, see the file `INSTALL' in the GPS
     sources for more details) to access information such as the
     location of the translation files.

`GPS_HOME'
     Override the variable HOME if present. All the configuration files
     and directories used by GPS are either relative to $HOME/.gps
     (%HOME%\.gps under Windows) if GPS_HOME is not set, or to
     $GPS_HOME/.gps (respectively %GPS_HOME%\.gps) if set.

`GPS_DOC_PATH'
     Set the search path for the documentation. See *Note Integrated
     Help:: for more details.

Files
=====

`$HOME/.gps'
     GPS state directory. Defaults to C:\.gps under Windows systems if
     HOME is not defined.

`$HOME/.gps/log'
     Log file created automatically by GPS

`$HOME/.gps/aliases'
     File containing the user-defined aliases (*note Defining Text
     Aliases::).

`$HOME/.gps/customize'
     Directory containing files with user-defined customizations.  All
     files found under this directory are loaded by GPS during start up.
     You can create/edit these files to add your own menu/tool-bar
     entries in GPS, or define support for new languages.  *note
     Customizing the Menu and Tool Bar:: and *note Adding Support for
     New Languages::.

`$HOME/.gps/custom_key'
     Contains all the key bindings defined in GPS. This file is
     automatically created if you have activated the dynamic key
     bindings feature (*note Customizing the Menu and Tool Bar::).

`$HOME/.gps/debugger.log'
     Log file created by the integrated debugger to trace of
     communication between GPS and gdb.

`$HOME/.gps/desktop'
     Desktop file in XML format (using the menu
     `File->Save...->Desktop'), loaded automatically if found.

`$HOME/.gps/gtkrc'
     The theme used by the gtk+ library on which gps is based. It
     allows you to configure the colors and fonts used in your
     application. *Note Defining New Styles and Key Bindings::.  See
     also `<prefix>/etc/gps/gtkrc'.

`$HOME/.gps/history'
     Contains the state and history of combo boxes (e.g. the
     `Run->Custom...' dialog).

`$HOME/.gps/preferences'
     Contains all the preferences in XML format, as specified in the
     preferences menu.

`$HOME/.gps/sessions'
     Directory containing the debugging sessions.

`$HOME/.gps/sessions/session'
     Each file in the `sessions' directory represents a particular
     session saved by the user.

`$HOME/.gps/traces.cfg'
     Default configuration for the system traces. These traces are used
     to analyze problems with GPS. By default, they are sent to the
     file `$HOME/.gps/log'.

`prefix'
     The prefix directory where GPS is installed, e.g `/opt/gps'.

`prefix/bin'
     The directory containing the GPS executables.

`prefix/etc/gps'
     The directory containing global configuration files for GPS.

`prefix/etc/gps/gtkrc'
     The global theme used by the gtk+ library. See also
     `$HOME/.gps/gtkrc'.

`prefix/etc/gps/pangorc'
     The pango (generic font handling) configuration file.

`prefix/etc/gps/pangox.aliases'
     File defining font aliases to X font set.

`prefix/lib'
     This directory contains the shared libraries used by GPS.

`prefix/doc/gps/html'
     GPS will look for all the documentation files under this directory.

`prefix/doc/gps/examples'
     This directory contains source code examples.

`prefix/doc/gps/examples/tutorial'
     This directory contains the sources used by the GPS tutorial.

`prefix/share/gps/aliases'
     Directory containing files with system-wide aliases (*note
     Defining Text Aliases::).

`prefix/share/gps/customize'
     Directory containing files with system-wide customizations (*note
     Adding Support for New Languages::).

`prefix/share/gps/gps-animation.gif'
     Animated image displayed in the top right corner of GPS to
     indicate that actions (e.g compilation) are on going.

`prefix/share/gps/gps-splash.jpg'
     Splash screen displayed by default when GPS is started.

`prefix/share/themes'
     Directory containing the Gtk+ predefined themes.

`prefix/share/make'
     Directory containing shared makefiles used by the multi-language
     build system.

`prefix/share/locale'
     Directory used to retrieve the translation files, when relevant.

Reporting Suggestions and Bugs
==============================

If you would like to make suggestions about GPS, or if you encountered
a bug, please report it to `mailto:report@gnat.com' following the usual
GNAT reports recommendations as explained in the file README.GNATPRO
for supported users, and in gnatinfo.txt for non supported users.

   Please try to include a detailed description of the problem,
including sources to reproduce it if possible/needed, and/or a scenario
describing the actions performed to reproduce the problem, as well as
the tools (e.g debugger, compiler, call graph) involved.

   The files `$HOME/.gps/log' and `$HOME/.gps/debugger.log' may also
bring some useful information when reporting a bug.

Solving Problems
================

This section addresses some common problems that may arise when using or
installing GPS.

`Non-privileged users cannot start GPS'
     Q: I have installed GPS originally as super user, and ran GPS
     successfully, but normal users can't.

     A: You should check the permissions of the directory $HOME/.gps
     and its subdirectories, they should be owned by the user.

`GPS crashes whenever I open a source editor'
     This is usually due to font problems. Editing the file
     `$HOME/.gps/preferences' and changing the name of the fonts, e.g
     changing Courier by Courier Medium, and Helvetica by Sans should
     solve the problem.

`GPS refuses to start the debugger'
     If GPS cannot properly initialize the debugger (using the menu
     `Debug->Initialize'), it is usually because the underlying debugger
     (gdb) cannot be launched properly. To verify this, try to launch
     the 'gdb' command from a shell (i.e outside GPS). If gdb cannot be
     launched from a shell, it usually means that you are using a wrong
     version of gdb (e.g a version of gdb built for Solaris 8, but run
     on Solaris 2.6).

`GPS is frozen during a debugging session'
     If GPS is no longer responding while debugging an application you
     should first wait a little bit, since some communications between
     GPS and gdb can take a long time to finish. If GPS is still not
     responding after a few minutes, you can usually get the control
     back in GPS by either typing <Ctrl-C> in the shell where you've
     started GPS: this should unblock it; if it does not work, you can
     kill the gdb process launched by GPS using the `ps' and `kill', or
     the `top' command under Unix, and the `Task Manager' under
     Windows: this will terminate your debugging session, and will
     unblock GPS.

`My Ada program fails during elaboration. How can I debug it ?'
     If your program was compiled with GNAT, the main program is
     generated by the binder. This program is an ordinary Ada (or C if
     the `-C' switch was used) program, compiled in the usual manner,
     and fully debuggable provided that the `-g' switch is used on the
     `gnatlink' command (or `-g' is used in the `gnatmake' command
     itself).

     The name of this package containing the main program is
     `b~xxx.ads/adb' where xxx is the name of the Ada main unit given
     in the gnatbind command, and you can edit and debug this file in
     the normal manner. You will see a series of calls to the
     elaboration routines of the packages, and you can debug these in
     the usual manner, just as if you were debugging code in your
     application.

`How can I debug the Ada run-time library ?'
     The run time distributed in binary versions of GNAT hasn't been
     compiled with debug information. Thus, it needs to be recompiled
     before you can actually debug it.

     The simplest is to recompile your application by adding the
     switches `-a' and `-f' to the `gnatmake' command line. This extra
     step is then no longer required, assuming that you keep the
     generated object and ali files corresponding to the GNAT run time
     available.

     Another possibility on Unix systems is to use the file
     `Makefile.adalib' that can be found in the adalib directory of
     your GNAT installation and specify e.g `-g -O2' for the `CFLAGS'
     switches.

`The GPS main window is not displayed'
     If when launching GPS, nothing happens, you can try to rename the
     `.gps' directory (see *Note Files::) to start from a fresh set up.

Index
*****

#ifdef:
          See ``Support for Cross References''.
-c:
          See ``The Preferences Dialog''.
-eval:
          See ``Scripts''.
-g:
          See ``Solving Problems''.
-gnatQ:
          See ``Support for Cross References''.
-k:
          See ``Support for Cross References''.
-load:
          See ``Scripts''.
-u:
          See ``The Preferences Dialog''.
a2ps:
          See ``The Preferences Dialog''.
action:
          See ``The Breakpoint Editor''.
Ada <1>:
          See ``The Preferences Dialog''.
Ada <2>:
          See ``The Data Window''.
Ada <3>:
          See ``Searching and Replacing''.
Ada <4>:
          See ``Description of the Projects''.
Ada <5>:
          See ``Source Navigation Contextual Menus''.
Ada <6>:
          See ``The Navigate Menu''.
Ada <7>:
          See ``Support for Cross References''.
Ada <8>:
          See ``Menu Items''.
Ada:
          See ``The Welcome Dialog''.
ADA_PROJECT_PATH:
          See ``Description of the Projects''.
add configuration variable:
          See ``The Project Explorer''.
add dependency:
          See ``The Project Explorer''.
add symbols:
          See ``The Debug Menu''.
ALI:
          See ``Support for Cross References''.
aliases <1>:
          See ``Files''.
aliases <2>:
          See ``Defining Text Aliases''.
aliases <3>:
          See ``The Preferences Dialog''.
aliases:
          See ``The Data Window''.
align:
          See ``The Data Window''.
all floating:
          See ``Floating Windows''.
analyze other file:
          See ``Dependency Browser''.
annotate:
          See ``The Version Control Contextual Menu''.
argument:
          See ``Customizing the Menu and Tool Bar''.
arguments:
          See ``The Debug Menu''.
ASCII <1>:
          See ``The Memory Window''.
ASCII:
          See ``Editing Sources''.
asm:
          See ``The Debugger Console''.
assembly <1>:
          See ``The Preferences Dialog''.
assembly:
          See ``The Debug Menu''.
attach:
          See ``The Debug Menu''.
AUnit:
          See ``Menu Items''.
auto refresh:
          See ``The Data Window''.
auto save <1>:
          See ``The Preferences Dialog''.
auto save:
          See ``General Information''.
autosave delay:
          See ``The Preferences Dialog''.
board <1>:
          See ``Debugger Issues''.
board:
          See ``The Debug Menu''.
breakpoint <1>:
          See ``The Preferences Dialog''.
breakpoint <2>:
          See ``Using the Source Editor when Debugging''.
breakpoint <3>:
          See ``The Breakpoint Editor''.
breakpoint:
          See ``The Debug Menu''.
breakpoint editor:
          See ``The Breakpoint Editor''.
browsers <1>:
          See ``The Preferences Dialog''.
browsers:
          See ``Scenarios and Configuration Variables''.
build <1>:
          See ``The Preferences Dialog''.
build <2>:
          See ``Compilation/Build''.
build <3>:
          See ``The Status Line''.
build <4>:
          See ``The Locations Tree''.
build:
          See ``The Messages Window''.
build progress:
          See ``The Preferences Dialog''.
C <1>:
          See ``The Preferences Dialog''.
C <2>:
          See ``The Memory Window''.
C <3>:
          See ``The Data Window''.
C <4>:
          See ``The Build Menu''.
C <5>:
          See ``The Project Menu''.
C:
          See ``Support for Cross References''.
C++ <1>:
          See ``The Preferences Dialog''.
C++ <2>:
          See ``The Build Menu''.
C++ <3>:
          See ``Searching and Replacing''.
C++ <4>:
          See ``The Project Menu''.
C++:
          See ``Support for Cross References''.
call graph <1>:
          See ``Call Graph''.
call graph <2>:
          See ``Scenarios and Configuration Variables''.
call graph:
          See ``Source Navigation Contextual Menus''.
call stack <1>:
          See ``The Call Stack Window''.
call stack:
          See ``The Debug Menu''.
called by:
          See ``Source Navigation Contextual Menus''.
calls:
          See ``Source Navigation Contextual Menus''.
cascade:
          See ``Maximized and Iconified Windows''.
case indentation:
          See ``The Preferences Dialog''.
case sensitive:
          See ``Searching and Replacing''.
category:
          See ``The Locations Tree''.
central area:
          See ``Moving Windows''.
character set:
          See ``The Preferences Dialog''.
clear:
          See ``Menu Items''.
clear_cache command:
          See ``The GPS Shell''.
clipboard <1>:
          See ``Using the Clipboard''.
clipboard:
          See ``The Tool Bar''.
clone:
          See ``The Data Window''.
close <1>:
          See ``Menu Items''.
close:
          See ``Closing Windows''.
code fixing:
          See ``Code Fixing''.
color:
          See ``The Preferences Dialog''.
column highlight:
          See ``The Preferences Dialog''.
column index:
          See ``The Preferences Dialog''.
command <1>:
          See ``The Debug Menu''.
command:
          See ``The Shell Window''.
command line <1>:
          See ``Command Line Options''.
command line:
          See ``The Welcome Dialog''.
comment:
          See ``Menu Items''.
compare <1>:
          See ``The Version Control Contextual Menu''.
compare:
          See ``The VCS Menu''.
compilation <1>:
          See ``Compilation/Build''.
compilation:
          See ``The Locations Tree''.
compile:
          See ``Scenarios and Configuration Variables''.
completion <1>:
          See ``The Preferences Dialog''.
completion:
          See ``General Information''.
configuration variable <1>:
          See ``Scenarios and Configuration Variables''.
configuration variable:
          See ``The Project Explorer''.
connect:
          See ``The Debug Menu''.
context length:
          See ``The Preferences Dialog''.
contextual menu <1>:
          See ``Using the Source Editor when Debugging''.
contextual menu <2>:
          See ``The Data Window''.
contextual menu <3>:
          See ``The Call Stack Window''.
contextual menu:
          See ``Source Navigation Contextual Menus''.
continuation line:
          See ``The Preferences Dialog''.
continue:
          See ``The Debug Menu''.
continue until:
          See ``Using the Source Editor when Debugging''.
copy <1>:
          See ``Using the Clipboard''.
copy:
          See ``Menu Items''.
core file:
          See ``The Debug Menu''.
creating configuration variable:
          See ``Scenarios and Configuration Variables''.
cross debugger:
          See ``The Debug Menu''.
cross environment <1>:
          See ``Working in a Cross Environment''.
cross environment:
          See ``Description of the Projects''.
cross references:
          See ``Support for Cross References''.
current:
          See ``General Information''.
current line:
          See ``Using the Source Editor when Debugging''.
current location:
          See ``Using the Source Editor when Debugging''.
custom editor:
          See ``Using an External Editor''.
customization <1>:
          See ``Customizing the Menu and Tool Bar''.
customization <2>:
          See ``Customizing and Extending GPS''.
customization:
          See ``Introduction''.
cut <1>:
          See ``Using the Clipboard''.
cut:
          See ``Menu Items''.
data <1>:
          See ``The Preferences Dialog''.
data <2>:
          See ``The Data Window''.
data:
          See ``The Debug Menu''.
data window:
          See ``The Data Window''.
debug <1>:
          See ``Using the Source Editor when Debugging''.
debug <2>:
          See ``The Debug Menu''.
debug:
          See ``Scenarios and Configuration Variables''.
debugger <1>:
          See ``Solving Problems''.
debugger <2>:
          See ``Files''.
debugger <3>:
          See ``The Preferences Dialog''.
debugger <4>:
          See ``Debugger Issues''.
debugger <5>:
          See ``The Debugger Console''.
debugger <6>:
          See ``The Debug Menu''.
debugger <7>:
          See ``Debugging''.
debugger:
          See ``The Tool Bar''.
debugger console:
          See ``The Debugger Console''.
debugging:
          See ``Debugging''.
declaration line:
          See ``The Preferences Dialog''.
delimiter <1>:
          See ``The Preferences Dialog''.
delimiter:
          See ``General Information''.
dependency:
          See ``The Preferences Dialog''.
dependency browser:
          See ``Dependency Browser''.
desktop:
          See ``The Preferences Dialog''.
detach:
          See ``The Debug Menu''.
diff:
          See ``The Preferences Dialog''.
directory <1>:
          See ``Menu Items''.
directory:
          See ``The Project Explorer''.
display:
          See ``Using the Source Editor when Debugging''.
display expression <1>:
          See ``The Data Window''.
display expression:
          See ``The Debug Menu''.
display line numbers:
          See ``The Preferences Dialog''.
docked <1>:
          See ``Moving Windows''.
docked:
          See ``Docked Windows''.
docked window:
          See ``Docked Windows''.
docking area:
          See ``Moving Windows''.
drag-n-drop:
          See ``Moving Windows''.
dynamic key binding:
          See ``The Preferences Dialog''.
edit:
          See ``Menu Items''.
edit project source file:
          See ``The Project Explorer''.
editing <1>:
          See ``Using the Source Editor when Debugging''.
editing <2>:
          See ``Editing Sources''.
editing:
          See ``Editing Files''.
editing configuration variable:
          See ``Scenarios and Configuration Variables''.
editor <1>:
          See ``The Preferences Dialog''.
editor <2>:
          See ``Using an External Editor''.
editor:
          See ``Introduction''.
emacs <1>:
          See ``The Preferences Dialog''.
emacs <2>:
          See ``Using an External Editor''.
emacs <3>:
          See ``Editing Sources''.
emacs <4>:
          See ``General Information''.
emacs:
          See ``Introduction''.
emacsclient:
          See ``Using an External Editor''.
entity:
          See ``The Project Explorer''.
entity browser:
          See ``Entity Browser''.
environment <1>:
          See ``Environment Variables''.
environment:
          See ``Environment''.
environment variables:
          See ``Environment Variables''.
errors <1>:
          See ``The Preferences Dialog''.
errors:
          See ``The Messages Window''.
examine entity:
          See ``Entity Browser''.
examine projects imported by:
          See ``The Project Browser''.
example <1>:
          See ``Command Line Options''.
example <2>:
          See ``Defining New Styles and Key Bindings''.
example <3>:
          See ``Adding Support for New Languages''.
example <4>:
          See ``Customizing the Menu and Tool Bar''.
example <5>:
          See ``The Preferences Dialog''.
example <6>:
          See ``The Debugger Console''.
example <7>:
          See ``The Assembly Window''.
example <8>:
          See ``Integrating existing build procedures with the GPS build system''.
example:
          See ``Using an External Editor''.
exception:
          See ``The Preferences Dialog''.
exec directory <1>:
          See ``The Project Wizard''.
exec directory:
          See ``Description of the Projects''.
execution <1>:
          See ``The Preferences Dialog''.
execution <2>:
          See ``The Execution Window''.
execution:
          See ``The Messages Window''.
execution window <1>:
          See ``The Execution Window''.
execution window:
          See ``The Messages Window''.
exit:
          See ``Menu Items''.
explorer:
          See ``The Project Explorer''.
explorer views:
          See ``The Project Explorer''.
external editor <1>:
          See ``The Preferences Dialog''.
external editor:
          See ``Using an External Editor''.
file <1>:
          See ``The Locations Tree''.
file:
          See ``The Project Explorer''.
file comparison:
          See ``The Preferences Dialog''.
file index:
          See ``The Preferences Dialog''.
file pattern:
          See ``The Preferences Dialog''.
file selector:
          See ``The File Selector''.
file view:
          See ``The Project Explorer''.
files:
          See ``Files''.
filter:
          See ``The Version Control Contextual Menu''.
find <1>:
          See ``Searching and Replacing''.
find <2>:
          See ``The Navigate Menu''.
find:
          See ``The Project Explorer''.
find all local references:
          See ``Source Navigation Contextual Menus''.
find all reads:
          See ``Source Navigation Contextual Menus''.
find all references <1>:
          See ``Source Navigation Contextual Menus''.
find all references:
          See ``The Navigate Menu''.
find all writes:
          See ``Source Navigation Contextual Menus''.
find next:
          See ``The Navigate Menu''.
find previous:
          See ``The Navigate Menu''.
finish:
          See ``The Debug Menu''.
float:
          See ``The Preferences Dialog''.
floating <1>:
          See ``Moving Windows''.
floating:
          See ``Floating Windows''.
font:
          See ``The Preferences Dialog''.
generate body:
          See ``Menu Items''.
gif <1>:
          See ``Files''.
gif:
          See ``Customizing the Menu and Tool Bar''.
GNAT <1>:
          See ``Description of the Projects''.
GNAT <2>:
          See ``Support for Cross References''.
GNAT <3>:
          See ``The Project Explorer''.
GNAT:
          See ``The Welcome Dialog''.
gnatmake:
          See ``Solving Problems''.
gnatpp:
          See ``Menu Items''.
gnatstub:
          See ``Menu Items''.
gnuclient:
          See ``Using an External Editor''.
goto body <1>:
          See ``Source Navigation Contextual Menus''.
goto body:
          See ``The Navigate Menu''.
goto declaration <1>:
          See ``Source Navigation Contextual Menus''.
goto declaration:
          See ``The Navigate Menu''.
goto file spec/body <1>:
          See ``Source Navigation Contextual Menus''.
goto file spec/body:
          See ``The Navigate Menu''.
goto line:
          See ``The Navigate Menu''.
gpr2make:
          See ``Description of the Projects''.
gps shell:
          See ``The GPS Shell''.
GPS_DOC_PATH:
          See ``Environment Variables''.
GPS_HOME:
          See ``Environment Variables''.
GPS_ROOT:
          See ``Environment Variables''.
graph disable:
          See ``The Debugger Console''.
graph display:
          See ``The Debugger Console''.
graph enable:
          See ``The Debugger Console''.
graph print:
          See ``The Debugger Console''.
graph undisplay:
          See ``The Debugger Console''.
Gtk+ <1>:
          See ``Files''.
Gtk+:
          See ``Defining New Styles and Key Bindings''.
gtkrc <1>:
          See ``Files''.
gtkrc:
          See ``Defining New Styles and Key Bindings''.
handle:
          See ``Docked Windows''.
help <1>:
          See ``Integrated Help''.
help:
          See ``Introduction''.
helper:
          See ``The Preferences Dialog''.
hexadecimal <1>:
          See ``The Memory Window''.
hexadecimal:
          See ``Editing Sources''.
hide:
          See ``The Data Window''.
highlight delimiter:
          See ``The Preferences Dialog''.
history <1>:
          See ``Files''.
history:
          See ``The Debug Menu''.
HOME:
          See ``Files''.
HTML <1>:
          See ``Integrated Help''.
HTML:
          See ``Introduction''.
icon:
          See ``The Data Window''.
iconified:
          See ``Maximized and Iconified Windows''.
iconify:
          See ``Multiple Document Interface''.
implicit dependency:
          See ``The Preferences Dialog''.
imported project:
          See ``Description of the Projects''.
indentation <1>:
          See ``The Preferences Dialog''.
indentation:
          See ``General Information''.
indentation level:
          See ``The Preferences Dialog''.
integrated help:
          See ``Integrated Help''.
interactive command <1>:
          See ``Customizing the Menu and Tool Bar''.
interactive command:
          See ``The Shell Window''.
interactive search <1>:
          See ``Defining New Styles and Key Bindings''.
interactive search <2>:
          See ``The VCS Explorer''.
interactive search:
          See ``The Project Explorer''.
interrupt:
          See ``The Debug Menu''.
introduction:
          See ``Introduction''.
ISO-8859-1:
          See ``The Preferences Dialog''.
jpeg <1>:
          See ``Files''.
jpeg:
          See ``Customizing the Menu and Tool Bar''.
key <1>:
          See ``Customizing the Menu and Tool Bar''.
key <2>:
          See ``The Preferences Dialog''.
key <3>:
          See ``The Memory Window''.
key <4>:
          See ``Searching and Replacing''.
key <5>:
          See ``Menu Items''.
key <6>:
          See ``Editing Sources''.
key <7>:
          See ``The Execution Window''.
key <8>:
          See ``The Locations Tree''.
key:
          See ``The Shell Window''.
key binding <1>:
          See ``Customizing the Menu and Tool Bar''.
key binding:
          See ``The Preferences Dialog''.
key theme:
          See ``The Preferences Dialog''.
kill:
          See ``The Debug Menu''.
limited with:
          See ``The Project Explorer''.
line index:
          See ``The Preferences Dialog''.
line terminator:
          See ``The Preferences Dialog''.
load <1>:
          See ``The Debug Menu''.
load:
          See ``Menu Items''.
local variables:
          See ``The Debug Menu''.
locate in explorer <1>:
          See ``The Project Browser''.
locate in explorer:
          See ``The Project Explorer''.
location <1>:
          See ``The Preferences Dialog''.
location:
          See ``The Locations Tree''.
locations tree <1>:
          See ``The Navigate Menu''.
locations tree:
          See ``The Locations Tree''.
log:
          See ``Files''.
look in:
          See ``Searching and Replacing''.
macro:
          See ``Support for Cross References''.
main unit:
          See ``Description of the Projects''.
main units:
          See ``The Project Wizard''.
main windows:
          See ``Description of the Main Windows''.
maximized <1>:
          See ``Moving Windows''.
maximized:
          See ``Maximized and Iconified Windows''.
MDI <1>:
          See ``The Preferences Dialog''.
MDI <2>:
          See ``Searching and Replacing''.
MDI <3>:
          See ``Multiple Document Interface''.
MDI:
          See ``The Work Space''.
memory view <1>:
          See ``The Preferences Dialog''.
memory view <2>:
          See ``Using the Source Editor when Debugging''.
memory view <3>:
          See ``The Memory Window''.
memory view <4>:
          See ``The Data Window''.
memory view:
          See ``The Debug Menu''.
menu <1>:
          See ``Customizing the Menu and Tool Bar''.
menu <2>:
          See ``The VCS Menu''.
menu <3>:
          See ``The Breakpoint Editor''.
menu <4>:
          See ``The Data Window''.
menu <5>:
          See ``The Debug Menu''.
menu <6>:
          See ``Debugging''.
menu <7>:
          See ``Searching and Replacing''.
menu <8>:
          See ``Using an External Editor''.
menu <9>:
          See ``Menu Items''.
menu <10>:
          See ``Moving Windows''.
menu <11>:
          See ``Floating Windows''.
menu <12>:
          See ``Docked Windows''.
menu <13>:
          See ``Maximized and Iconified Windows''.
menu <14>:
          See ``The Execution Window''.
menu:
          See ``The Locations Tree''.
menu bar:
          See ``The Menu Bar''.
messages <1>:
          See ``The Preferences Dialog''.
messages <2>:
          See ``Menu Items''.
messages <3>:
          See ``The Status Line''.
messages:
          See ``The Messages Window''.
messages window:
          See ``The Messages Window''.
moving:
          See ``Moving Windows''.
Multiple Document Interface <1>:
          See ``The Preferences Dialog''.
Multiple Document Interface <2>:
          See ``Searching and Replacing''.
Multiple Document Interface <3>:
          See ``Multiple Document Interface''.
Multiple Document Interface:
          See ``The Work Space''.
name space:
          See ``Support for Cross References''.
naming scheme <1>:
          See ``The Project Wizard''.
naming scheme:
          See ``Description of the Projects''.
navigate:
          See ``The Navigate Menu''.
navigation:
          See ``Source Navigation''.
new file:
          See ``Menu Items''.
new view:
          See ``Menu Items''.
next:
          See ``The Debug Menu''.
next tag:
          See ``The Navigate Menu''.
nexti:
          See ``The Debug Menu''.
object directory <1>:
          See ``The Project Wizard''.
object directory:
          See ``Description of the Projects''.
opaque:
          See ``The Preferences Dialog''.
open:
          See ``Menu Items''.
options:
          See ``Command Line Options''.
overloaded:
          See ``Support for Cross References''.
paste <1>:
          See ``Using the Clipboard''.
paste:
          See ``Menu Items''.
patch:
          See ``The Preferences Dialog''.
png:
          See ``Customizing the Menu and Tool Bar''.
preferences <1>:
          See ``Files''.
preferences <2>:
          See ``The Preferences Dialog''.
preferences <3>:
          See ``Using the Source Editor when Debugging''.
preferences <4>:
          See ``Using an External Editor''.
preferences <5>:
          See ``Menu Items''.
preferences <6>:
          See ``Floating Windows''.
preferences <7>:
          See ``Docked Windows''.
preferences:
          See ``The Welcome Dialog''.
pretty print:
          See ``Menu Items''.
previous tag:
          See ``The Navigate Menu''.
print <1>:
          See ``The Preferences Dialog''.
print <2>:
          See ``Using the Source Editor when Debugging''.
print:
          See ``Menu Items''.
PrintFile:
          See ``The Preferences Dialog''.
problems:
          See ``Solving Problems''.
progress bar:
          See ``The Status Line''.
project <1>:
          See ``The Preferences Dialog''.
project <2>:
          See ``Customizing your Projects''.
project <3>:
          See ``Project Handling''.
project <4>:
          See ``Support for Cross References''.
project <5>:
          See ``Menu Items''.
project <6>:
          See ``The Project Explorer''.
project:
          See ``The Welcome Dialog''.
project attribute:
          See ``Scenarios and Configuration Variables''.
project browser:
          See ``The Project Browser''.
project description:
          See ``Description of the Projects''.
project explorer <1>:
          See ``Searching and Replacing''.
project explorer <2>:
          See ``The Project Explorer''.
project explorer <3>:
          See ``Scenarios and Configuration Variables''.
project explorer <4>:
          See ``Project Handling''.
project explorer:
          See ``The Project Explorer''.
project file <1>:
          See ``Description of the Projects''.
project file:
          See ``The Project Explorer''.
project menu:
          See ``The Project Menu''.
project properties editor:
          See ``The Project Properties Editor''.
project variable <1>:
          See ``Scenarios and Configuration Variables''.
project variable:
          See ``The Project Explorer''.
project view:
          See ``The Project Explorer''.
project wizard:
          See ``The Project Wizard''.
protection domain <1>:
          See ``The Breakpoint Editor''.
protection domain:
          See ``The Debug Menu''.
quit:
          See ``Menu Items''.
range size:
          See ``The Preferences Dialog''.
recent:
          See ``Menu Items''.
recompute project:
          See ``The Project Menu''.
redo:
          See ``Menu Items''.
references:
          See ``Source Navigation Contextual Menus''.
refresh <1>:
          See ``The Debug Menu''.
refresh:
          See ``Dependency Browser''.
registers:
          See ``The Debug Menu''.
regular expression:
          See ``Searching and Replacing''.
relative path:
          See ``The Preferences Dialog''.
remote copy:
          See ``The Preferences Dialog''.
remote shell:
          See ``The Preferences Dialog''.
remove dependency:
          See ``The Project Explorer''.
removing variable:
          See ``Scenarios and Configuration Variables''.
renaming entities:
          See ``Call Graph''.
replace <1>:
          See ``Searching and Replacing''.
replace:
          See ``The Navigate Menu''.
replace with:
          See ``Searching and Replacing''.
resource file:
          See ``Defining New Styles and Key Bindings''.
run <1>:
          See ``The Debug Menu''.
run:
          See ``The Execution Window''.
save:
          See ``Menu Items''.
save all:
          See ``Menu Items''.
save as:
          See ``Menu Items''.
save default desktop:
          See ``Menu Items''.
save desktop:
          See ``Menu Items''.
saving projects:
          See ``The Project Explorer''.
scope:
          See ``The Breakpoint Editor''.
scripts:
          See ``Scripting GPS''.
search <1>:
          See ``Searching and Replacing''.
search <2>:
          See ``The Navigate Menu''.
search <3>:
          See ``The Locations Tree''.
search:
          See ``The Project Explorer''.
search all occurrences:
          See ``Searching and Replacing''.
search context:
          See ``Searching and Replacing''.
search for:
          See ``Searching and Replacing''.
select all:
          See ``Menu Items''.
selection:
          See ``The Preferences Dialog''.
separate unit:
          See ``Support for Cross References''.
shell <1>:
          See ``Customizing the Menu and Tool Bar''.
shell <2>:
          See ``The Tools Menu''.
shell <3>:
          See ``The Shell Window''.
shell:
          See ``The Messages Window''.
shell window <1>:
          See ``The Shell Window''.
shell window:
          See ``The Messages Window''.
show:
          See ``The Data Window''.
Show absolute paths:
          See ``The Project Explorer''.
show dependencies:
          See ``The Project Browser''.
show dependencies for:
          See ``Dependency Browser''.
show files depending on:
          See ``Dependency Browser''.
show files depending on file:
          See ``Dependency Browser''.
Show files from project only:
          See ``The Project Explorer''.
Show flat view:
          See ``The Project Explorer''.
show implicit dependencies:
          See ``Dependency Browser''.
show projects depending on:
          See ``The Project Browser''.
show recursive dependencies:
          See ``The Project Browser''.
show system files:
          See ``Dependency Browser''.
show type:
          See ``The Data Window''.
show value:
          See ``The Data Window''.
side:
          See ``Moving Windows''.
solving problems:
          See ``Solving Problems''.
source browsing:
          See ``Source Browsing''.
source directory:
          See ``Description of the Projects''.
source file <1>:
          See ``Using the Source Editor when Debugging''.
source file <2>:
          See ``Description of the Projects''.
source file:
          See ``Editing Sources''.
source navigation:
          See ``Source Navigation''.
splash screen:
          See ``The Preferences Dialog''.
status:
          See ``The Status Line''.
status bar:
          See ``The Status Line''.
status line:
          See ``The Status Line''.
step:
          See ``The Debug Menu''.
stepi:
          See ``The Debug Menu''.
strip blanks:
          See ``The Preferences Dialog''.
sub project:
          See ``Description of the Projects''.
submitting bugs:
          See ``Reporting Suggestions and Bugs''.
substitution:
          See ``Customizing the Menu and Tool Bar''.
suggestions:
          See ``Reporting Suggestions and Bugs''.
switches <1>:
          See ``The Project Wizard''.
switches:
          See ``Description of the Projects''.
switches editor:
          See ``The Switches Editor''.
syntax highlighting:
          See ``Using the Source Editor when Debugging''.
tabulation:
          See ``The Preferences Dialog''.
tag:
          See ``The Navigate Menu''.
target:
          See ``The Debug Menu''.
task <1>:
          See ``The Breakpoint Editor''.
task:
          See ``The Debug Menu''.
terminate:
          See ``The Debug Menu''.
testing:
          See ``Menu Items''.
theme:
          See ``Files''.
thread:
          See ``The Debug Menu''.
title:
          See ``Maximized and Iconified Windows''.
title bar <1>:
          See ``The Data Window''.
title bar:
          See ``Closing Windows''.
tool bar <1>:
          See ``Customizing the Menu and Tool Bar''.
tool bar <2>:
          See ``The Preferences Dialog''.
tool bar:
          See ``The Tool Bar''.
tools <1>:
          See ``Tools''.
tools:
          See ``Description of the Projects''.
tooltip <1>:
          See ``The Preferences Dialog''.
tooltip <2>:
          See ``Using the Source Editor when Debugging''.
tooltip:
          See ``General Information''.
top level:
          See ``Floating Windows''.
tty:
          See ``The Preferences Dialog''.
uncomment:
          See ``Menu Items''.
undo:
          See ``Menu Items''.
unit testing:
          See ``Menu Items''.
Unix <1>:
          See ``Solving Problems''.
Unix <2>:
          See ``Defining New Styles and Key Bindings''.
Unix <3>:
          See ``Customizing the Menu and Tool Bar''.
Unix <4>:
          See ``Integrating existing build procedures with the GPS build system''.
Unix:
          See ``Scenarios and Configuration Variables''.
unmaximized <1>:
          See ``Moving Windows''.
unmaximized:
          See ``Maximized and Iconified Windows''.
update value:
          See ``The Data Window''.
url <1>:
          See ``Description of the Projects''.
url <2>:
          See ``Using the Clipboard''.
url:
          See ``Using an External Editor''.
variable <1>:
          See ``Scenarios and Configuration Variables''.
variable:
          See ``The Project Explorer''.
VCS:
          See ``The Project Wizard''.
VCS explorer:
          See ``The VCS Explorer''.
version control <1>:
          See ``The VCS Menu''.
version control <2>:
          See ``The VCS Explorer''.
version control:
          See ``Version Control System''.
Version Control System:
          See ``The Project Wizard''.
vertical layout:
          See ``The Preferences Dialog''.
vi:
          See ``Using an External Editor''.
view <1>:
          See ``The Debugger Console''.
view:
          See ``Menu Items''.
vim:
          See ``Using an External Editor''.
visual diff <1>:
          See ``The Preferences Dialog''.
visual diff:
          See ``Visual Comparison''.
VxWorks:
          See ``Description of the Projects''.
VxWorks AE:
          See ``The Breakpoint Editor''.
welcome dialog <1>:
          See ``The Preferences Dialog''.
welcome dialog:
          See ``The Welcome Dialog''.
whole word:
          See ``Searching and Replacing''.
window manager:
          See ``Multiple Document Interface''.
window selection:
          See ``Selecting Windows''.
Windows <1>:
          See ``Solving Problems''.
Windows <2>:
          See ``Files''.
Windows <3>:
          See ``Environment Variables''.
Windows <4>:
          See ``Customizing the Menu and Tool Bar''.
Windows <5>:
          See ``Integrating existing build procedures with the GPS build system''.
Windows <6>:
          See ``Using an External Editor''.
Windows <7>:
          See ``Menu Items''.
Windows <8>:
          See ``The File Selector''.
Windows:
          See ``The Project Explorer''.
work space <1>:
          See ``Docked Windows''.
work space <2>:
          See ``Multiple Document Interface''.
work space:
          See ``The Work Space''.
wrench icon:
          See ``Code Fixing''.
X-Window:
          See ``Using the Clipboard''.
xpm:
          See ``Customizing the Menu and Tool Bar''.
yank <1>:
          See ``Using the Clipboard''.
yank:
          See ``Menu Items''.
zoom:
          See ``The Data Window''.
zoom in:
          See ``The Data Window''.
zoom out:
          See ``The Data Window''.
Table of Contents
*****************


Using the GNAT Programming System

Introduction

Description of the Main Windows
  The Welcome Dialog
  The Menu Bar
  The Tool Bar
  The Work Space
  The Project Explorer
    The explorer views
    The configuration variables
  The Messages Window
  The Shell Window
  The Locations Tree
  The Execution Window
  The Status Line

Integrated Help
  The Help Menu
  Adding New Help Files

Multiple Document Interface
  Selecting Windows
  Closing Windows
  Maximized and Iconified Windows
  Docked Windows
  Floating Windows
  Moving Windows

Editing Files
  General Information
  Editing Sources
    Key bindings
  The File Selector
  Menu Items
    The File Menu
    The Edit Menu
  Using an External Editor
  Using the Clipboard

Source Navigation
  Support for Cross References
  The Navigate Menu
  Source Navigation Contextual Menus

Project Handling
  Description of the Projects
    Project files and GNAT tools
    Contents of project files
  Scenarios and Configuration Variables
    Creating new configuration variables
    Editing existing configuration variables
  The Project Explorer
  The Project Menu
  The Project Wizard
    Project Naming
    VCS Selection
    Source Directories Selection
    Build Directory
    Naming Scheme
    Main Units
    Switches
  The Project Properties Editor
  The Switches Editor
  The Project Browser

Searching and Replacing

Compilation/Build
  The Build Menu
  Integrating existing build procedures with the GPS build system

Source Browsing
  General Issues
  Call Graph
  Dependency Browser
  Entity Browser

Debugging
  The Debug Menu
    Debug
    Data
  The Call Stack Window
  The Data Window
    Description
    Manipulating items
      Moving items
      Colors
      Icons
  The Breakpoint Editor
    Scope/Action Settings for VxWorks AE
  The Memory Window
  Using the Source Editor when Debugging
  The Assembly Window
  The Debugger Console

Version Control System
  The VCS Explorer
  The VCS Menu
  The Version Control Contextual Menu

Tools
  The Tools Menu
  Visual Comparison
  Code Fixing

Working in a Cross Environment
  Customizing your Projects
  Debugger Issues

Customizing and Extending GPS
  The Preferences Dialog
  Customizing the Menu and Tool Bar
    Redefining key bindings
    Adding menu items
    Adding tool bar buttons
    Macro arguments
  Adding Support for New Languages
  Defining Text Aliases
    Aliases files
  Defining New Styles and Key Bindings
    Toplevel declarations
    Defining new styles
    Defining new key bindings
  Scripting GPS
    Scripts
    The GPS Shell

Environment
  Command Line Options
  Environment Variables
  Files
  Reporting Suggestions and Bugs
  Solving Problems

Index


