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

   Using the GNAT Programming System

   GPS, the GNAT Programming System

   Version 1.4.0

   Date: 2003/10/27 08:57:24

   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 and
key manager dialogs; 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.

   By default, files specified on the command line are taken as is and
can be absolute or relative pathnames. In addition, if you prepend a
filename with the `=' character, then GPS will look for the file in the
source search path of the project.

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

   Under Windows, it is possible to drop files (coming e.g. from the
Explorer) in any of these views with the following behavior: a project
file dropped will be loaded; any other file will open a source editor
on this file.

   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.  For more
     information on supported languages, *Note Supported Languages::.

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

   Every time a new category is created, as a result of a compilation
or a search operation for instance, the first entry of that category is
automatically selected, and the corresponding editor opened. This
behavior can be controlled through a preference `Jump To First
Location'.

   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 one or several progress bars.

   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 bars are used to display information about on going
operations such as builds, searches, or VCS commands. These tasks
operate in the background, and can be paused/resumed via a contextual
menu. This contextual menu is available by right-clicking on the
progress bars themselves or on the corresponding lines in the Task
Manager. See *Note The Task Manager::

The Task Manager
================

The Task Manager window lists all the currently running GPS operations
that run in the background, such as builds, searches or VCS commands.

   For each of these tasks, the Task Manager shows the status of the
task, and the current progress. The execution of theses tasks can be
suspended using a contextual menu, brought up by right-clicking on a
line.

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.

   It can also be set programmatically through the GPS shell or any of
the scripting languages. This is done with

     add_doc_path "/home/foo"

   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
     Instead of putting all the windows inside a notebook, GPS lets 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 cannot 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 cannot 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, that is that you want to see the windows as you resize them.

   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 and size of the title (name)
of a 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.

Splitting Windows
=================

The window in the central area of the MDI can be split at will, through
any combination of horizontal and vertical splits.  This feature
requires at least two windows (text editors, browsers,...)  to be
superimposed in the central area. Selecting either the `Window->Split
Horizontally' or `Window->Split Vertically' menus will then split the
selected window in two. In the left (resp. top) pane, the currently
selected window will be left on its own. The rest of the previously
superimposed windows will be put in the right (resp. bottom) pane. You
can then in turn split these remaining windows to achieve any layout
you want.

   All split windows can be resized interactively by dragging the
handles that separate them, just as is done for docked windows. A
preference (menu `Edit->Preferences' controls whether this resizing is
done in opaque mode or border mode. In the latter case, only the new
handle position will be displayed while the mouse is dragged.

   The current layout is lost when you select one of the menus
`Window->Cascade', `Window->Tile Horizontally', `Window->Tile
Vertically' or `Window->Unmaximized'. It is also changed if you destroy
the last visible window in a pane. For instance, if you have split the
central area in two, with one editor only on each side, closing any
editor will result in an unsplit central area.

   You may want to bind the key shortcuts to the menus `Window->Split
Horizontally' as well as `Window->Split Vertically' using either the
preference `Dynamic Key Binding', or the key manager. In addition, if
you want to achieve an effect similar to e.g. the standard Emacs
behavior (where <control-x 2> splits a window horizontally, and
<control-x 3> splits a window vertically), you can use the key manager
(*note The Key Manager Dialog::).

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 unselect `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 you rely on windows handling facilities supported by your
system or window manager but not available in GPS. This might also be
useful if you want to have windows on various virtual desktops, should
your window manager support this.

   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 to floating and back, in any order.

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

   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 not 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 Microsoft Windows
systems.

   While you keep the mouse button pressed, and move the mouse around,
the selected drop area is highlighted with a dashed border. This shows
precisely where the window would be put if you were to release the
mouse button at that point.

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

The central area
     If the windows in that area are unmaximized, the window you are
     dropping (the current window) will acquire the same state.
     However, if the windows are currently maximized in the central
     area, or even if the latter was split horizontally, vertically or
     any combination of these, the location of the current window is
     indicated by the dashed rectangle: either in the pane where you
     released the mouse button, or on one of the sides of that pane
     (splitting as needed).

Docking areas
     The window will be immediately added to this area after dropping it
     and a new notebook will be created as needed.

     In some cases, you might want to create a docking area that is not
     currently visible (for instance, it is often useful to put the
     location window in the right docking area).

     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
     If you drop a window outside of GPS (for instance, on the
     background of your screen), the window will be floated.

   If you maintain the <shift> key pressed while dropping the window,
this might result in a copy operation instead of a simple move. For
instance, if you are dropping an editor, a new view of the same editor
will be created, resulting in two views present in GPS: the original
one is left at its initial location, and a second view is created at
the new location.

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 Contextual Menus for Source Navigation::
     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
     key manager dialog, *Note The Key Manager 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 type of information displayed depends on the current state of
     GPS.

     In normal mode, the entity kind and the location of declaration 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.  Otherwise, 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 key manager
     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::.

Current block highlighting
     If this preference is enabled, the editor will highlight the
     current block of code, e.g. the current `begin...end' block, or
     loop statement, etc...

     The block highlighting will also take into account the changes
     made in your source code, and will recompute automatically the
     current block when needed.

     This capability is currently implemented for Ada, C and C++
     languages.

Block folding
     When enabled, the editor will display `-' icons on the left side,
     corresponding to the beginning of subprograms. If you click on one
     of these icons, all the lines corresponding to this subprogram are
     hidden, except the first one. As for the block highlighting, these
     icons are recomputed automatically when you modify your sources
     and are always kept up to date.

     This capability is currently implemented for Ada, C and C++
     languages.

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' or `vi'. *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.

     A new view can also be created by keeping the <shift> key pressed
     while drag-and-dropping the editor (see *Note Moving Windows::).
     This second method is preferred, since you can then specify
     directly where you want to put the new view. The default when
     using the menu is that the new view is put on top of the editor
     itself.

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.

     If you press the down arrow key, the focus will move to the list of
     completions, so that you can select a file from this list without
     using the mouse.

     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.

     This dialog will only show each file once. If you have extended
     projects in your hierarchy, some files may be redefined in some
     extending project. In this case, only the files from the extending
     project are shown, and you cannot have access through this dialog
     to the overridden files of the extended project. Of course, you
     can still use the project explorer or the standard `File->Open'
     menu to open these files.

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 More
     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 window contents, optionally saving it
     interactively if it has been modified. The Print Command specified
     in the preferences is used if it is defined. On Unix this command
     is required; on Windows it is optional.

     On Windows, if no command is specified in the preferences the
     standard Windows print dialog box is displayed. This dialog box
     allows the user to specify the target printer, the properties of
     the printer, which pages to print (all, or a specific range of
     pages), the number of copies to print, and, when more than one
     copy is specified, whether the pages should be collated.  Pressing
     the Cancel button on the dialog box returns to GPS without
     printing the window contents; otherwise the specified pages and
     copies are printed on the selected printer. Each page is printed
     with a header containing the name of the file (if the window has
     ever been saved). The page number is printed on the bottom of each
     page.  *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.

Fold all blocks
     Collapse all the blocks in the current file.

Unfold all blocks
     Uncollapse all the blocks in the current file.

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

    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 test harness. See AUnit documentation for more
          details.

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

Key shortcuts
     Give access to the key manager dialog, to associate commands with
     special keys. *Note The Key Manager 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 be found in
     the PATH, and thus is not supported on Windows systems. Under
     Windows systems, you can use the `custom' editor instead.

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

Saving Files
============

After you have finished modifying your files, you need to save them.
The basic method to do that is to select the menu `File->Save', which
saves the currently selected file.

   You can also use the menu `File->Save As...' if you want to save the
file with another name, or in another directory.

   If you have multiple files to save, another possibility is to use
the menu `File->Save More->All'. This will open a dialog listing all
the currently modified editors that need saving. You can then select
individually which one should be saved, and click on `Save' to do the
actual saving.

   When calling external commands, such as compiling a file, if the
`Auto save' preference is disabled, this same dialog is also used, to
make sure that e.g. the compiler will take into account your local
changes.  If the preference is enabled, the saving is performed
automatically.

   You can conveniently select or unselect all the files at once by
clicking on the title of the first column (labelled Select). This will
toggle the selection status of the first line, and have the same status
for all other editors.

   If you press `Cancel' instead of `Save', no saving will take place,
and the action that displayed this dialog is also cancelled. Such
actions can be for instance starting a compilation command, a VCS
operation, or quitting GPS with unsaved files.

Remote Files
============

GPS has a basic support for working with files on remote hosts. This
includes a number of protocols, described below, which allow you to
read a file from a remote host, edit it locally, and then save it
transparently to the remote machine.

   For now, the support for remote files is only available through the
GPS shell window. You start editing a remote file by typing a line
similar to

     edit protocol://user@machine/full/path

   where "protocol" should be replaced by the name of the protocol you
want to use, "user" is the login name you wish to use on the remote
"machine", and "/full/path" is the full path on the remote machine to
access the file.

   The user name is optional. If it is the same as on the local
machine, you can omit the user name as well as the "@" sign.

   Likewise, the machine name is optional, if you want to get a file
from the local host. This can be used to access files belonging to
another user. In this case, you need to specify the "@" sign, but do
not insert a machine name right after it.

   Remote files can also be used if you want to work with GPS, but the
machine on which the files are found isn't supported by GPS.

   The following protocols are supported:

ssh
     This protocol is based on the ssh command line tool, which must
     therefore be available in the path. It provides encrypted and
     secure connections to the remote host. Files are transfered
     inline, that is the connection is established the first time you
     access the remote host, and kept open for all further access.

     Although ssh can be setup not to require a password, GPS will
     automatically detect if a password is asked and open a dialog to
     query it.

     The remote system must be a Unix-like system with support for
     standard Unix commands like `test', `echo', `rm' and `ls'.

     In the sample shell command above, you would replace the word
     "protocol" with "ssh" to use this protocol.

rsh
     This protocol behaves like ssh, except that the connections are
     not encpryted.  However, this protocol is generally available on
     all Unix machines by default.

     It has the same requirements that the ssh protocol. To use it,
     substitute the word "rsh" to "protocol" in the example above.

telnet
     This protocol is based on the standard telnet protocol. It behaves
     much like the two protocols above, with an unencrypted connection.

     To use it, substitute the word "telnet" to "protocol" in the
     example above.

scp
     This protocol is also based on one of the tools of the ssh suite.
     It provides encrypted connections, and uses a mixture of ssh and
     scp connections.  Various commands like querying the timestamp of
     a file are executed through a permanent ssh connection, whereas
     files are downloaded and uploaded through a one-time scp command.

     It basically has the same behavior as the ssh protocol, although
     it might be slightly slower since a new connection has to be
     established every time a file is fetched from, or written to the
     remote host. However, it might work better than ssh if the file
     contains 8 bit characters.

     To use it, substitute the word "scp" to "protocol" in the example
     above.

rsync
     Just like scp is based on ssh, this protocol is based on rsh. It
     depends on the external tool rsync, and uses a mixture of a rsh
     connection for commands like querying the timestamp of a file, and
     one-time connections with rsync to transfer the files.

     Rsync is specially optimized to transfer only the parts of a file
     that are different from the one already on the remote host.
     Therefore, it will generally provide the best performance when
     writing the file back to the remote host.

     If you set up the environment variable RSYNC_RSH to ssh before
     starting gps, the connection will then be encrypted when
     transfering the files.

     To use this protocol, substitute the word "rsync" to "protocol" in
     the example above.

ftp
     This protocol provides only limited capabilities, but can be used
     to retrieve or write a file back through an ftp connection,
     possibly even through an anonymous ftp connection.

     To use this protocol, substitute the word "ftp" to "protocol" in
     the example above.

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

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

GPS provides cross-reference navigation for program entities, such as
types, procedures, functions, variables, ..., defined in your
application. The cross-reference support in GPS relies on
language-specific tools as explained below.

Ada
     The GNAT compiler is used to generate the cross-references
     information needed by GPS. This means that you must compile your
     application before you browse through the cross-references or view
     various graphs in GPS.  If sources have been modified, you should
     recompile the modified files.

     If you need to navigate through sources that do not compile (e.g
     after modifications, or while porting an application), GNAT can
     still generate partial cross-reference 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 your non compilable sources.

     There are a few special cases where GPS cannot 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 cannot 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:
     namespaces are currently ignored (no specific processing is done
     for namespaces); minimal support for templates; 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 the availability of
     cross-reference information.  *Note 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 the availability of cross-reference
     information.  *Note 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

Start Of Statement
     Move the cursor position to the start of the current statement,
     does nothing if the current position is not inside a statement.

End Of Statement
     Move the current cursor position to the end of the statement, does
     nothing if the current position is not inside a statement.

Next Subprogram
     Move the current cursor position to the start of the next
     procedure, function, task, protected record or entry.

Previous Subprogram
     Move the current cursor position to the start of the previous
     procedure, function, task, protected record or entry.

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

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

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

This contextual menu is available from any source editor.  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 subprograms 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 subprograms 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. 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 recommended reading if you want to use some
of the more advanced capabilities of project files which are not yet
supported by the graphical interface.

   GPS can load any project file, even those that you have been edited
manually. Furthermore, you can manually edit project files created by
GPS.

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

   GPS doesn't preserve the layout of whole content of manually created
project after you have edited them in GPS. For instance, comments are
not currently preserved. Likewise, multiple case statements in the
project will be coalesced into a single case statement. This
normalization is required for GPS to be able to preserve the previous
semantic of the project in addition to the new settings.

   All command-line GNAT tools are project aware, meaning that the
notion of project goes well beyond GPS' user interface. Most
capabilities of project files can be accessed without using GPS itself,
making 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 project files as GNAT itself:

   * 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
-------------------------

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 a 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 (compiling
them with the appropriate switches, put the resulting files in the
right directories, ...).

   Each project contains the following information (see the GNAT user's
guide for the full list)

   * List of imported projects:    When you are compiling 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 cannot 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 refers 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 supports cross
     environment software development: GPS itself can    run on a given
     host, such as GNU/Linux, while compilations, runs and    debugging
     occur on a different remote host, such as Sun/Solaris.

     GPS 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:    Project files provide a simple way to specify the
     compiler and    debugger commands 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 the specific file being
     processed, and the programming    language it is written in.


Supported Languages
===================

Another information stored in the project is the list of languages that
this project knows about. GPS support any number of language, with any
name you choose. However, advanced support is only provided by default
for some languages (Ada, C and C++), and you can specify other
properties of the languages through customization files (*note Adding
Support for New Languages::).

   By default, the graphical interface will only give you a choice of
languages among the ones that are known to GPS at that point, either
through the default GPS support or your customization files. But you
can also edit the project files by hand to add support for any language.

   Languages are a very important part of the project definition. For
each language, you should specify a naming scheme that allows GPS to
associate files with that language. You would for instance specify that
all `.adb' files are Ada, all `.txt' files are standard text files, and
so on.

   Only the files that have a known language associated with them are
displayed in the `Project View', or available for easy selection
through the `File->Open From Project' menu. Similarly, only these files
are shown in the Version Control System interface.

   It is therefore important to properly setup your project to make
these files available conveniently in GPS, although of course you can
still open any file through the `File->Open' menu.

   If your project includes some README files, or other text files, you
should add "txt" as a language (or any other name you want), and make
sure that these files are associated with that language in the `Project
properties editor'.

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 host computer environment, or
directly set in GPS (using the small area on top of the project
explorer (*Note The Project Explorer::).

   This facility 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 the software).  In this configuration scenario,
all the attributes (source directories, tools, ...) remain the same,
except for the compilation 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 host computer environment,
     although you can of course change its value later on inside GPS.


   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 source directories, object directories or list of
source files have 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 updated 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 (a 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 test 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 project. On exit, the wizard
     asks whether the newly created project should be loaded. If you
     select `Yes', the new project will replace the currently loaded
     project hierarchy.

`Open'
     This menu opens a file selection dialog, so that any existing
     project can be loaded into 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 typical way to access this wizard is through the
`Project->New...' menu. On exit, the wizard will ask whether the newly
created project should replace the currently loaded ones.

   The project wizard is also launched 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.

   Child projects can be created from this dialog. These are project
whose name is of the form `Parent.Child'. However, the generated project
is invalid, since one of the restrictions for these projects, which is
currently not enforced by GPS, is that the project must import or
extend its parent project. Therefore, you will not be able to load this
project in GPS until you have manually edited it.

   In this page, you should also select what languages the source files
in this project are written in. Currently supported languages 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 allows you to select which Version
Control system is to be 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 other developers 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 a directory 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 directory
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
line up or down.

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

The object directory is the location where the files resulting from the
compilation of sources (e.g. `.o' files) are placed.  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 this respect, and allows you to specify the
default extension for the files in a given programming language. GPS
makes a distinction between spec (or header) files, which generally
contain 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 this 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 fields at the bottom of the
window, and press the update button.

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

The main units of 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 each partition in the project.

   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 project. 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 you can do 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.

   The project propoerties editor is divided in three parts:

The attributes editor
     The contents of this editor are 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 cannot 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 the attributes editor apply.

     Clicking on the left title bar (untitled, on the left of the
     `Scenario' label) will select or unselect 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 time 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 projects it imports directly, 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 displays all the projects that directly import 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.
     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.

     Clicking on the arrow on the right will display the list of all
     possible contexts. This list includes:

    `Project Explorer'
          Search in the project explorer. An extra Scope box will be
          displayed where you can specify the scope of your search,
          which can be a set of: `Projects, Directories, Files,
          Entities'. The search in entities may take a long time,
          search each file is parsed during the search.

    `Open Files'
          Search in all the files that are currenly open in the source
          editor. The Scope entry is described in the `Files...'
          section below.

    `Files...'
          Search in a given set of files. An extra Files box will be
          displayed where you can specify the files by using standard
          shell (Unix or Windows) regular expression, e.g. `*.ad?' for
          all files ending with .ad and any trailing character. The
          directory specified where the search starts, and the
          Recursive search button whether sub directories will be
          searched as well.

          The Scope entry is used to restrict the search to a set of
          language constructs, e.g. to avoid matching on comments when
          you are only interested in actual code, or to only search
          strings and comments, and ignore the code.

    `Files From Project'
          Search in all the files from the project, including files
          from project dependencies. The Scope entry is described in
          the `Files...' section above.

    `Current File'
          Search in the current source editor.  The Scope entry is
          described in the `Files...' section above.

    `Project Browser'
          Search in the project browser (*note The Project Browser::).

    `Help'
          Search in the help window.

   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.

     This button is reset to its default value whenever you modify the
     searched pattern or the replacement text.

`"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. You can also commute between these two modes by
     selecting the arrow on the right of the `Search for:' field.  The
     grammar followed by the regular expressions is similar to the Perl
     and Python regular expressions grammar, and is documented in the
     GNAT run time file `g-regpat.ads'. To open it from GPS, you can
     use the open from project dialog (`File->Open From Project...')
     and type g-regpat.ads. See *Note Open From Project:: for more
     information on this dialog.

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

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.

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.

    Project
          Build all source files defined in your top level project.

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

    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 (e.g. libraries or objects to link with).

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
     LDFLAGS += $(FOO_BASE_DIR)/<build>/libfoo.a
     
     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.

Exporting
     The entire contents of a browser can be exported as a `png' image
     using the entry `Export...' 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.

   The integrated debugger provided by GPS is using an improved version
of the GVD engine, so the functionalities between GVD and GPS are very
similar.  If you are familiar with GVD, you may be interested in reading
*Note Upgrading from GVD to GPS:: which explains the differences
between the two environments.

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

   Note that you can create multiple debuggers by using the `Initialize'
menu several times: this will create a new debugger each time.  All the
debugger-related actions (e.g. stepping, running) are performed on the
current debugger, which is represented by the current debugger console.
To switch between debuggers, simply select its corresponding console.

   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 Current', that will terminate your current debug
session, or the menu `Debug->Terminate' that will terminate all your
debug sessions at once.

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 Current
     Terminate the current 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.

Terminate
     Terminate all your debug sessions. Same as `Terminate Current' if
     there is only one debugger open.

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 for
a given breakpoint, by first selecting a breakpoint in the list, and
then by clicking on the Advanced button, which will display a new
dialog 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.

Upgrading from GVD to GPS
=========================

This section is intended for users already familiar with GVD, in order
to help them transitioning to GPS. If you have not used GVD, you may
want to skip this section.

   This section outlines the differences between GVD and GPS, and also
lists some of the advantages of GPS compared to GVD.

Command Line Switches
---------------------

The following command line switches related to debugging are available
in GPS:

`--debug'
     Automatically start a debug session, as done by GVD.  You can also
     specify a program name and its arguments, so this option replaces
     the `--pargs' and `executable-file' arguments in GVD.

`--debugger'
     Equivalent to the same GVD option, with the difference that
     arguments can be specified as well, replacing the `--dargs' option.

`--target'
     Same as in GVD.

   For example, the equivalent of the following command line:

     $ gvd --debugger=gdb-5 executable --pargs 1 2 3

   would be

     $ gps --debug='executable 1 2 3' --debugger=gdb-5

Menu Items
----------

All the debugger-related menus in GVD can be found under the 'Debug'
menu in GPS, with the following mapping:

`File->xxx'
     available under `Debug->Debug->xxx'

`Program->xxx'
     available under `Debug->xxx'

`Data->xxx'
     available under `Debug->Data->xxx'

   The menu `File->New Debugger...' is replaced by the combination of
the menu `Debug->Initialize' and the project properties, available
under `Project->Edit Project Properties' where you can similarly
specify your Debugger Host (called Tools Host), your Program Host, the
Protocol used by the underlying debugger to communicate with the
target, and the name of the debugger.  To conveniently switch between
multiple debugger configurations, we recommend to use a scenario
variable and set different properties based on the value of this
variable. See *Note Scenarios and Configuration Variables:: and *Note
Working in a Cross Environment:: for more details.

Tool Bar Buttons
----------------

GPS provides by default fewer debugger buttons than GVD, because some
buttons are actually not used very often, and others have been merged.
In addition, it will be possible in the future to completely configure
the GPS tool bar.

`Run'
     Menu `Debug->Run...' (<F2>)

`Start'
     Start/Continue button

`Step'
     Step button

`Stepi'
     Menu `Debug->Step Instruction' (<Shift-F5>)

`Next'
     Next button

`Nexti'
     Menu `Debug->Next Instruction' (<Shift-F6>)

`Finish'
     Finish button

`Cont'
     Start/Continue button

`Up'
     Up button

`Down'
     Down button

`Interrupt'
     Menu `Debug->Interrupt' (<Control-Blackslash>)

Key Short Cuts
--------------

The same key shortcuts have been kept by default between GVD and GPS
except for the Interrupt menu, which is now <Control-Backslash> instead
of <Esc>.

Contextual Menus
----------------

All the debugger-related contextual menus can now be found under the
`Debug' sub-menu.

   The only difference is the contextual menu `Show' used to display
the assembly dump of the current code. It is replaced by the menu
`Debug->Data->Assembly', see *Note The Assembly Window:: for more
details.

File Explorer
-------------

The file explorer provided in GVD is replaced by the `Project View' and
the `File View' in GPS.

   When using the `--debug' command line switch and no explicit project
file, GPS will automatically create a project file in a way very
similar to what GVD does to display its file explorer, and available
under the `Project View'.

   In addition, the `File View' gives access to any file in your file
system, even if it is not available as part of the debug information.

Advantages of GPS
-----------------

The advantages when using GPS instead of GVD can be classified in two
main categories: when not using project files, and when using them.

   When not using project files, you get access to the following
advantages in GPS:

   * Complete source editor including indentation, shortcuts, multiple
     views, ...  See *Note Editing Files:: for more details.

   * A more stable and robust debugger engine.  The debugger engine
     included in GPS corresponds to GVD version 2.0.  In effect, GPS is
     the new version of GVD.

   * Integrated help, see *Note Integrated Help:: for more details.

   * Better look and feel.  GPS uses the new version of the graphical
     toolkit used by GVD, which provides a modern look and feel and a
     more stable interface under Windows (with additions such as
     support for the mouse wheel).

   * Support for version control systems which is integrated and
     available through a few mouse clicks or key bindings.  See *Note
     Version Control System:: for more details.

   * A more flexible window handling, see *Note Multiple Document
     Interface:: for more details.

   When using project files, you will get, in addition to the
advantages listed above:

   * Source navigation, see *Note Source Navigation:: for more details.

   * Source Browsers, in particular the entity browser, a nice
     complement of the debugger data window.  See *Note Source
     Browsing:: for more details.

   * Builds, see *Note Compilation/Build:: for more details.

   * Semantic support.  In particular, GPS is be able to e.g.
     differentiate variables from types when displaying a contextual
     menu, which is not possible in GVD.

   * Flexibility of project files, see *Note Project Handling:: for
     more details.

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.

    `Added'
          The file has been added remotely but is not yet updated in
          the local view.

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

Compare against revision...
     Show a visual comparison between the local file and a specific
     revision of that file in the repository.

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.

     When using CVS, the annotations are clickable. Left-clicking on an
     annotation line will query and display the changelog associated to
     the specific revision for this line.

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.

Revert
     Revert the file to the latest version in the repository, erasing
     your local changes.

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 sub-projects
          Brings up the VCS Explorer with all the source files
          contained in the project and all imported sub-projects.

    Query status for project and sub-projects
          Queries the status for all the source files contained in the
          project and all imported sub-projects.

    Update project and sub-projects
          Updates all the source files in the project and all imported
          sub-projects.

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

Task Manager
     *Note The Task Manager::.

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.

   Similarly, if you are running the underlying debugger (gdb) on a
remote machine, you can specify the name of this machine by setting the
`Tools host' field of the project properties.

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.

         Jump To First Location
               Whether the first entry of the location window should be
               selected automatically, and thus whether the
               corresponding editor should be immediately open.

         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.

    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
                    Determine whether matching delimiters should be
                    highlighted. The list of delimiters includes:
                    `{}[]()'

              Autosave delay
                    The period (in seconds) after which an 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.

              Block highlighting
                    Whether the editor should highlight the current
                    block.  The current block depends on the
                    programming language, and will include e.g.
                    procedures, loops, if statements, ...

              Block folding
                    Whether the editor should provide the ability to
                    fold/unfold blocks.

              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 under Unix systems), you can use an
                    external terminal command, e.g:

                         xterm -geo 80x50 -exe 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 inline 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

              Default font
                    The font used in the source editor.

              Keywords
                    Font and colors used to highlight keywords.

              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.

              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.

              Delimiter highlighting color
                    Color for highlighting delimiters.

         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;

              Reserved word casing
                    How the editor should handle reserved words casing.
                    `Unchanged' will keep the casing as-is; `Upper'
                    will change the casing of all reserved words to
                    upper case; `Lower' will change the casing to lower
                    case; `Mixed' will change the casing to mixed case
                    (all characters to lower case except first
                    character and characters after an underscore which
                    are set to upper case).  `Smart_Mixed' As above but
                    do not force upper case characters to lower case.

              Identifier casing
                    How the editor should handle identifiers casing.
                    The values are the same as for the Reserved word
                    casing preference.

              Format operators/delimiters
                    Whether the editor should add extra spaces around
                    operators and delimiters if needed.  If enabled, an
                    extra space will be added when needed in the
                    following cases: before an opening parenthesis;
                    after a closing parenthesis, comma, semicolon;
                    around all Ada operators (e.g. `<=', `:=', `=>',
                    ...)

              Align declarations on colons
                    Whether the editor should automatically align
                    colons in declarations and parameter lists. Note
                    that the alignment is computed by taking into
                    account the current buffer up to the current line
                    (or end of the current selection), so if
                    declarations continue after the current line, you
                    can select the declarations lines and hit the
                    reformat key.

              Align associations on arrows
                    Whether the editor should automatically align
                    arrows in associations (e.g. aggregates or function
                    calls). See also previous preference.

         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.

    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.
                    This setup is only taken into account when a new
                    debugger is initialized, and will not modify a
                    running debugger (use the breakpoint editor for
                    running debuggers).

              Execution window
                    Specifies whether the debugger should create a
                    separate execution window for the program being
                    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 the source editor should display
                    blue dots 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.

              Click-able 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
               External program used to print files.

               This program is required under Unix systems in order to
               print, and is set to `a2ps' by default.  If `a2ps' is
               not installed on your system, you can download it from
               <www.inf.enst.fr/~demaille/a2ps>

               Under Windows systems, this program is optional and is
               empty by default, since a built-in printing is provided.
               An external tool will be used if specified, such as the
               PrintFile freeware utility available from
               <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::)

         File pattern
               Pattern used to detect file locations and the type of
               the output 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 from two
               to five parenthesized subexpressions corresponding to
               the file, line, column, warnings or style error 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.

         Warning index
               Index of the warning identifier in the file pattern.

         Style index
               Index of the style error identifier in the file pattern.

    Project

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


The Key Manager Dialog
======================

The key manager is accessible through the menu `Edit->Key Shortcuts'.
This dialog provides an easy way to associate key shortcuts with
actions.  These actions are either predefined in GPS, or defined in
your own customization files, as documented in *Note Customizing the
Menu and Tool Bar::.  It also provides an easy way to redefine the menu
shortcuts.

   Actions are referenced by their name, and are grouped into
categories. These categories indicate when the action applies. For
instance, the indentation command only applies in source editors,
whereas the command to change the current window applies anywhere in
GPS. The categories correspond in fact to filters that indicate when
the action can be executed. You can create your own new categories by
using the `<filter>' tag in the customization files (*note Customizing
the Menu and Tool Bar::).

   Through the key manager, you can define key bindings similar to what
Emacs uses (<control-x> followed by <control-k> for instance). To
register such key bindings, you need to press the `Grab' button as
usual, and then type the shortcut. The recording of the key binding
will stop a short while after the last key stroke.

   This facility for creating complex shortcuts is not available for
menu items yet.

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.

Customization files
-------------------

The GPS menu bar can be customized through XML files. These files are
found through three possible mechanisms, described here in the order in
which they are searched. Files with the `.xml' extension found through
`GPS_CUSTOM_PATH' or the user's directory can override any setup found
in the system directory. Likewise, files found in the user's directory
can override any file found in the `GPS_CUSTOM_PATH' directories.

   Note that only files with the `.xml' extension are considered.

   * System wide customization

     The `INSTALL/share/gps/customize' directory, where `INSTALL' is
     the name of the GPS installation directory, should contain the
     files that will always be loaded whenever GPS is loaded, by any
     user on the system.

   * `GPS_CUSTOM_PATH'

     This environment variable can be set before launching GPS. It
     should contain a list of directories, separated by semicolons
     (';') on Windows systems and colons (':') on Unix systems. All the
     files found in these directories will be searched for
     customization files.

     This is a convenient way to have project-specific customization
     files. You can for instance create scripts, or icons, that set the
     appropriate value for the variable and then start GPS. Depending
     on your project, this allows you to load specific aliases which do
     not make sense for other projects.

   * User directory

     The directory `$HOME/.gps/customize' on Unix systems, and
     `%HOME%\.gps\customize' on Windows systems, can also contain
     customization files which are parsed at startup. This is a
     convenient way for users to define their own customization, that
     they want to load no matter which project they are working on.

   The format of these files have changed in GPS 1.3.0. A conversion
program is provided that will automatically convert all files in the
customization directory to the new format. This conversion tool is
called `gps2custom-1.3', and must be run manually.

   These files must be utf8-encoded by default. However, you can
specify any encoding you wish through the standard `<?xml
encoding="..." ?>' declaration, as in the following example:

     <?xml version="1.0" encoding="iso-8859-1">
     <submenu>
       <title>encoded text/title>
     </submenu>

   Any given XML file can contain customization for various aspects of
GPS, mixing aliases, new languages or menus,... in a single file. This
is a convenient way to distribute your customization to other users.

   These files must be valid XML files, i.e. must start with the
`<?xml?>' tag, and contain a single root XML node, the name of which is
left to your consideration. The general format is therefore

     <?xml version="1.0" ?>
     <root_node>
        ...
     </root_node>

   XML comments are not supported in these files.

   The list of valid XML child nodes that can be specified under <root>
is described in later sections. This includes:

`<action>'
     (*note Defining Actions::)

`<key>'
     (*note Binding actions to keys::)

`<submenu>'
     (*note Adding new menus::)

`<alias>'
     (*note Defining Text Aliases::)

`<language>'
     (*note Adding Support for New Languages::)

`<button>'
     (*note Adding tool bar buttons::)

`<vsearch-pattern>'
     (*note Defining new search patterns::)

`<tool>'
     (*note Adding support for new tools::)

`<filter>'
     (*note Filtering actions::)

`<contextual>'
     (*note Adding contextual menus::)

Defining Actions
----------------

These files distinguish the actions from their associated menus or key
bindings. These actions can take on several forms: external commands,
shell commands and predefined commands, as will be explained in more
details below.

   The general form to define new actions is to use the `<action>' tag.
This tag accepts the following attributes:

`name   (mandatory)'
     This tag must be specified. It provides the name by which the
     action is referenced in other parts of the customization files,
     for instance when it is associated with a menu or a toolbar
     button. The name can contain any character, although it is
     recommended to avoid XML special characters.

`output  (optional)'
     If specified, this attribute indicates where the output of the
     commands will be sent by default. This can be overriden by each
     command, using the same attribute for `<shell>' and `<external>'
     tags, *Note Redirecting the command output::.

`show-command (optional)'
     If specified, this attribute indicates whether the text of the
     command itself should be displayed at the same location as its
     output. Neither will be displayed if the output is hidden. The
     default is to show the command along with its output.

     This attribute can be overriden for each command.

   The `<action>' can have one or several children, all of which define
a particular command to execute. All of these commands are executed one
after the other, unless one of them fails in which case the following
commands are not executed.

   The following XML tags are valid children for `<action>'.
`<external>'
     This defines a command to execute through the system (i.e. a
     standard Unix or Windows command)

     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 `external' tag would look like:

          <action name="my_command">
            <external>cmd /c c:\.gps\my_scripts\my_cmd.cmd</external>
          </action>

     This tag accepts the following attributes:

    `show-command (optional)'
          This attribute can be used to override the homonym attribute
          specified for    the `<action>' tag.

    `output (optional)'
          This attribute can be used to override the homonym attribute
          specified for    the `<action>' tag.

    `on-failure (optional)'
          This attribute specifies a shell command to be executed if
          the external    command fails. Typically, this is used to
          parse the output of the command    and fill the location
          window appropriately (*note Processing the tool output::).

          For instance, the following action spawn an external tool,
          and parses its    output to the location window and the
          automatic fixing tool if the external    tool happens to
          fail. You must put the value of the `on-failure' on a
          single line in the XML file.

          Remember also to quote special XML character like '"' in the
          value of the    attribute. The output of the command that
          failed can be obtained through the    "%1" parameter.

               <action name="launch tool to location" >
                 <external on-failure="locations_parse &quot;
                    &quot;&quot;%1 &quot;&quot;&quot; category;
                    codefix_parse &quot;&quot;&quot;%1 &quot;
                    &quot;&quot; category" >tool-path</external>
               </action>

    `on-failure-lang (optional)'
          This attribute specifies the shell language in which the
          above attribute is    written. By default, this is the GPS
          shell.

    `progress-regexp (optional)'
          This attribute specifies a regular expression that the output
          of the    command will be checked against. Every time the
          regular expression matches,    it should provide two numeric
          values that are used to display the usual    progress
          indicators at the bottom-right corner of the GPS window, as
          happens during regular compilations.

          The name of the action is printed in the progress bar while
          the action is    executing.

               <action name="progress" >
                  <external progress-regexp="(\d+) out of (\d+).*$"
                            progress-current="1"
                            progress-final="2"
                            progress-hide="true">gnatmake foo.adb
                  </external>
               </action>

    `progress-current (optional)'
          This is the opening parenthesis count index in
          `progress-regexp'    that contains the current step.

    `progress-final   (optional)'
          This is the opening parenthesis count index in
          `progress-regexp'    that contains the current last step.
          This last index can grow as    needed. For example, gnatmake
          will output the number of    the file it is currently
          examining, and the total number of files to be    examined.
          However, that last number may grow up, since parsing a new
          file    might generate a list of additional files to parse
          later on.

    `progress-hide    (optional)'
          If this attribute is set to the value "true", then all the
          lines that    match `progress-regexp' and are used to compute
          the progress will    not be displayed in the output console.
          For any other value of this    attribute, these lines are
          displayed along will the rest of the output.

`<shell>'
     As well as external commands, you can use custom menu items to
     invoke GPS commands using the `shell' tag. These are command
     written in one of the shell scripts supported by GPS.

     This tag supports the same `show-command' and `output' attributes
     as the `<action>' tag.

     The following example shows how to create two actions to invoke
     the `help' interactive command and to open the file `main.c'.

          <action name="help">
            <shell>help</shell>
          </action>
          <action name="edit">
            <shell>edit main.c</shell>
          </action>

     By default, commands are expected to be written in the GPS shell
     language.  However, you can specify the language through the
     `lang' attribute. Its default value is `"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.

          <action name="current file uses">
            <shell lang="shell">File %f</shell>
            <shell lang="shell">File.uses %1</shell>
          </action>

`<description>'
     This tag contains a description for the command, which is used in
     the graphical editor for the key manager. *Note The Key Manager
     Dialog::.

`<filter>, <filter_and>, <filter_or>'
     This is the context in which the action can be executed, *Note
     Filtering actions::.

   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.

     <action "xterm in current directory">
       <shell lang="shell">cd %d</shell>
       <external>xterm</external>
     </action>

   As seen in some of the examples above, some special strings are
expanded by GPS just prior to executing the command. These are the
"%f", "%d",.. See below for a full list.

   More information on chaining commands is provided in *Note Chaining
commands::.

   Some actions are also predefined in GPS itself. This include for
instance aliases expansion, manipulating MDI windows,... All known
actions (predefined and the ones you have defined in your own
customization files) can be discovered by opening the keyshortcut
editor (`Edit->Keyshortcuts' menu).

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

When an action is defined, you can use macro arguments to pass to your
shell or external 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.

`%d'
     The currently directory.

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

`%P'
     The root project. This is the name of the project, not the project
     file.

`%pp'
     The current project file pathname. If a file is selected, this is
     the project file to which the source file belongs.

`%PP'
     The root project pathname.

`%pps'
     This is similar to `%pp', except it returns the project name
     prepended with `-P', or an empty string if there is no project
     file selected and the current source file doesn't belong to any
     project. This is mostly for use with the GNAT command line tools.

`%PPs'
     This is similar to `%PP', except it returns the project name
     prepended with `-P', or an empty string if the root project is the
     default project.  This is mostly for use with the GNAT command
     line tools.

`%(p|P)[r](d|s)[f]'
     Substituted by the list of sources or directories of a given
     project. This list is a list of space-separated, quoted names (all
     names are surrounded by double quotes, for proper handling of
     spaces in directories or file names).

    `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. This file is never deleted by GPS, it
          is your responsability to do so.

   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.

Filtering actions
-----------------

By default, an action will execute in any context in GPS. The user just
selects the menu or key, and GPS tries to execute the action.

   It is possible to restrict when an action should be considered as
valid. If the current context is incorrect for the action, GPS will not
attempt to run anything, and will display an error message for the user.

   Actions can be restricted in several ways:

  1. Using macro arguments (*note Macro arguments::).  If you are using
     one of the macro arguments defined in the previous section,
     anywhere in the chain of commands for that action, GPS will first
     check that the information is available, and if not will not start
     running any of the shell commands or external commands for that
     action.

     For instance, if you have specified `%F' as a parameter to one of
     the commands, GPS will check prior to running the action that
     there is a current file. This can be either a currently selected
     file editor, or for instance that the project explorer is
     selected, and a file node inside it is also selected.

     You do not have to specify anything else, this filtering is
     automatic

  2. Defining explicit filters Explicit restrictions can be specified
     in the customization files. These are specified through the
     `<filter>', `<filter_and>' and `<filter_or>' tags, see below.

     These tags can be used to further restrict when the command is
     valid. For instance, you can use them to specify that the command
     only applies to Ada files, or only if a source editor is currently
     selected.


The filters tags
................

   Such filters can be defined in one of two places in the
customization files:

  1. At the toplevel At the same level as other tags such as
     `<action>', `<menu>' or `<button>' tags, you can define named
     filters. These are general filters, that can be referenced
     elsewhere without requiring code duplication. They also appear
     explicitely in the keyshortcuts editor if at least one action is
     depending on them.

  2. As a child of the `<action>' tag Such filters are anonymous,
     although they provide exactly the same capabilities as the ones
     above. These are mostly meant for simple filters, or filters that
     you use only once, or don't want to appear in the keyshortcuts
     manager.

   There are three different kinds of tags:

`<filter>'
     This defines a simple filter. This tag takes no child tag.

`<filter_and>'
     All the children of this tag are composed together to form a
     compound filter.  They are evaluated in turn, and as soon as one
     of them fails, the whole filter fails. Children of this tag can be
     of type `<filter>', `<filter_and>' and `<filter_or>'.

`<filter_or>'
     All the children of this tag are composed together to form a
     compound filter.  They are evaluated in turn, and as soon as one
     of them succeeds, the whole filter succeeds. Children of this tag
     can be of type `<filter>', `<filter_and>' and `<filter_or>'.

   If several such tags are found following one another under an
`<action>' tag, they are combined through "or", i.e. any of the filters
may match for the action to be executed.

   The `<filter>', `<filter_and>' and `<filter_or>' tags accept the
following set of common attributes:

`name       (optional)'
     This attribute is used to create named filters, that can be reused
     elsewhere in actions or compound filters through the `id'
     attribute. The name can take any form. This is also the name that
     appears in the context of the keyshortcuts editor.

`error      (optional)'
     This is the error message printed in the GPS console if the filter
     doesn't match, and thus the action cannot be executed. If you are
     composing filters through `<filter_and>' and `<filter_or>', only
     the error message of the top-level filter will be printed.

   In addition, the `<filter>' has the following specific attributes:

`id         (optional)'
     If this attribute is specified, all other attributes are ignored.
     This is used to reference a named filter previously defined. Here
     is for instance how you can make an action depend on a named
     filter:

            <filter name="Test filter" language="ada" />
            <action name="Test action" >
               <filter id="Test filter" />
               <shell>pwd</shell>
            </action>

     A number of predefined filters are predefined by GPS itself. The
     full list   appears in the keyshortcut editor, and is listed here:

    `Source editor'
          This filter will only match if the currently selected window
          in GPS is an   editor.

`language   (optional)'
     This attribute specifies the name of the language that must be
     associated with the current file to match. For instance, if you
     specify `ada', you must have an Ada file selected, or the action
     won't execute. The language for a file is found by GPS following
     several algorithms (file extensions, and via the naming scheme
     defined in the project files).

`shell_cmd  (optional)'
     This attribute specifies a shell command to execute. The output
     value of this command is used to find whether the filter matches:
     if it returns "1" or "true", the filter matches. In any other
     case, the filter fails.

     Note that currently no expansion of macro arguments (%f, %p,...)
     is done in this command.

`shell_lang (optional)'
     This attribute specifies in which language the shell command above
     is written.  Its default value indicates that the command is
     written using the GPS shell.

`module     (optional)'
     This attribute specifies that the filter only matches if the
     current window was setup by this specific GPS module. For
     instance, if you specify "Source_Editor", this filter will only
     match when the active window is a source editor.

     The list of module names can be obtained by typing `lsmod' in the
     shell console at the bottom of the GPS window.

     This attribute is mostly useful when creating new contextual menus.

   When several attributes are specified for a `<filter>' node (which
is not possible with `id'), they must all match for the action to be
executed.

     <!-- The following filter will only match if the currently selected
          window is a text editor editing an Ada source file -->
     
     <filter_and name="Source editor in Ada" >
         <filter language="ada" />
         <filter id="Source editor" />
     </filter_and>
     
     <!-- The following action will only be executed for such an editor -->
     
     <action name="Test Ada action" >
         <filter id="Source editor in Ada" />
         <shell>pwd</shell>
     </action>
     
     <!--  An action with an anonymous filter. It will be executed if the
           selected file is in Ada, even if the file was selected through
           the project explorer  -->
     
     <action name="Test for Ada files" >
         <filter language="ada" />
         <shell>pwd</shell>
     </action>

Adding new menus
----------------

These commands can be associated with menus, tool bar buttons and keys.
All of these use similar syntax.

   Binding a menu to an action is done through the `<menu>' tag.  This
tag takes the following attributes:

`action  (mandatory)'
     This attribute specifies which action to execute when the menu is
     selected by the user. If no action by this name was defined, no
     new menu is added.

`before  (optional)'
     It specifies the name of another menu item before which the new
     menu should be inserted. The reference menu must have been created
     before, otherwise the new menu is inserted at the end. This
     attribute can be used to control where precisely the new menu
     should be made visible.

`after   (optional)'
     This attribute is similar to `before', but has a lower priority.
     If it is specified, and there is no `before' attribute, it
     specifies a reference menu after which the new menu should be
     inserted.

   It should also have one XML child called `<title>' which specifies
the label of the menu 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 specify which menu this new item is added to by putting the
`<menu>' tag to a `<submenu>' tag. The latter also takes a `<title>' as
a child. You can add items or sub menus to existing menus, using titles
for menus that already exist.

   For example, this adds an item named `mymenu' to the standard `Edit'
menu.

     <submenu>
       <title>Edit</title>
       <menu action="current file uses">
          <title>mymenu</title>
       </menu>
     </submenu>

   Use the `/' separator to identify the submenu in a menu. For
example, this adds a new item "stats" to the standard "unit testing"
submenu in "tools".

     <submenu>
       <title>Tools/unit testing</title>
       <menu action="execute my stats">
         <title>stats</title>
       </menu>
     </submenu>

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

Adding contextual menus
-----------------------

The actions can also be used to contribute new entries in the contextual
menus everywhere in GPS. These menus are displayed when the user presses
the right mouse button, and should only show actions relevant to the
current context.

   Such contributions are done through the `<contextual>' tag, which
takes one mandatory attribute `action', which is the name of the action
to execute, and must be defined elsewhere in one of the customization
files.

   It accepts one child tag, `<Title>' which specifies the name of the
menu entry. If this child is not specified, the menu entry will use the
name of the action itself.

   The new contextual menu will only be shown if the filters associated
with the action match the current context.

   For instance, the following example inserts a new contextual menu
which prints the name of the current file in the GPS console. This
contextual menu is only displayed in source editors.

     <action name="print current file name" >
        <filter module="Source_Editor" />
        <shell>echo %f</shell>
     </action>
     
     <contextual action="print current file name" >
        <Title>Print Current File Name</Title>
     </contextual>

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

As an alternative to creating new menu items, you can create new
buttons on the tool bar, with a similar syntax, by using the `<button>'
tag. As for the `<menu>' tag, it requires an `action' attribute which
specifies what should be done when the button is pressed. The button is
not created if no such action was created.

   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 `<button>' tag indicates a
separator in the tool bar.

   A title can also be specified with `<title>'. This will be visible
only if the user choses to see both text and icons in the tool bar.

   The following example defines a new button:

     <button action="execute my stats">
        <title>stats</title>
        <pixmap>/my_pixmaps/button.jpg</pixmap>
     </button>

Binding actions to keys
-----------------------

All the actions defined above can be bound to specific key shortcuts
through the `<key>' attribute. As usual, it requires one `<action>'
attribute to specify what to do when the key is pressed.

   This tag doesn't contain any child tag. Instead, its text contents
specified the keyboard shortcut. The name of the key can be prefixed by
`control-', `alt-', `shift-' or any combination of these to specify the
key modifiers to apply.

   You can also define multiple key bindings similar to Emacs's by
separating them by a space. For instance, `control-x control-k' means
that the user should press <control-x>, followed by a <control-k> to
activate the corresponding action.

   Use an empty string to describe the keybinding if you wish to
deactivate a preexisting binding. The second example below deactivates
the standard binding.

     <key action="expand alias">control-o</key>
     <key action="Jump to matching delimiter" />

   Multiple actions can be bound to the same key binding. The first one
with a filter valid for the current context is executed. If no action
with a filter can be executed, then the first action with no filter
will be executed.

Defining new search patterns
----------------------------

The search dialog contains a number of predefined search patterns for
Ada and C. These are generally complex regular expressions, presented
in the dialog with a more descriptive name. This includes for instance
"Ada assignment", which will match all such assignments.

   You can define your own search patterns in the customization files.
This is done through the `<vsearch-pattern>' tag. This tag can have a
number of children tags:

`<name>'
     This tag is the string that is displayed in the search dialog to
     represent the new pattern. This is the text that the user will
     effectively see, instead of the often hard to understand regular
     expression.

`<regexp>'
     This tag provides the regular expression to use when the pattern
     has been selected by the user. Be careful that you must protect
     reserved XML characters such as '<' and replace them by their
     equivalent expansion ("&lt;" for this character).

     This accepts one optional attribute, named `case-sensitive'. This
     attribute accepts one of two possible values ("true" or "false")
     which indicates whether the search should distinguish lower case
     and upper case letters. Its default value is "false".

`<string>'
     This tag provides a constant string that should be searched.  Only
     one of `<regexp>' and `<string>' should be provided. If both
     exists, the first `<regep>' child found is used. If there is none,
     the first `<string>' child is used.

     The tag accepts the same optional attribute `case-sensitive' as
     above

   Here is a small example on how the "Ada assignment" pattern was
defined.

     <vsearch-pattern>
       <name>Ada: assignment</name>
       <regexp case-sensitive="false">\b(\w+)\s*:=</regexp>
     </vsearch-pattern>

Full example
------------

The following example is a full example for one of the files in the
customization directory. The only thing that hasn't been described
before is the first line of the file, which is required to make it a
valid XML file.

     <?xml version="1.0"?>
     <Custom>
       <action name="action1">
         <external>external-command 1</external>
       </action>
     
       <action name="action2">
         <shell>edit %f</shell>
       </action>
     
       <submenu>
         <title>custom menu</title>
         <menu action="action1">
           <title>item 1</title>
         </menu>
     
         <submenu>
           <title>other menu</title>
           <menu action="action2">
             <title> (etc..)
           </menu>
     
           <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 external command `external-command 1', a sub menu named `other
menu', etc...

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), 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. Therefore, you can either
define new languages in a separate file, or reuse a file where you
already define actions and menus.

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

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

`Parent'
     If set to the name of an existing language (e.g. `Ada', `C++') or
     another custom language, this language will inherit by default all
     its properties from this language. Any field explicitely defined
     for this language will override the inherited settings.

`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, and consider using the
     `Extension' tag instead.  This tag must be unique.

`Body_Suffix'
     A string describing the suffix of body/implementation files for
     this language.  This tag works in coordination with the
     `Spec_Suffix', so that the user can choose to easily go from one
     file to the other.  This tag must be unique.

`Extension'
     A string describing one of the valid extensions for this language.
     There can be several such children. The extension must start with
     a '.' character

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

`Engine'
     The name of a dynamic library providing one or several of the
     functions described below.

     The name can be a full pathname, or a short name. E.g. under most
     Unix systems if you specify `custom', GPS will look for
     `libcustom.so' in the `LD_LIBRARY_PATH' run time search path. You
     can also specify explicitly e.g. `libcustom.so' or
     `/usr/lib/libcustom.so'.

     For each of the following five items, GPS will look for the
     corresponding symbol in `Engine' and if found, will call this
     symbol when needed.  Otherwise, it will default to the static
     behavior, as defined by the other language-related items
     describing a language.

     You will find the required specification for the C and Ada
     languages to implement the following functions in the directory
     `<prefix>/share/gps/doc/examples/language' of your GPS
     installation.  `language_custom.ads' is the Ada spec file;
     `language_custom.h' is the C spec file; `gpr_custom.ad?' are
     example files showing a possible Ada implementation of the
     function `Comment_Line' for the GPS project files (`.gpr' files),
     or any other Ada-like language; `gprcustom.c' is the C version of
     gpr_custom.adb.

`Comment_Line'
     Name of a symbol in the specified shared library corresponding to a
     function that will comment or uncomment a line (used to implement
     the menu `Edit->Un/Comment Lines').

`Parse_Constructs'
     Name of a symbol in the specified shared library corresponding to a
     function that will parse constructs of a given buffer.

     This procedure is used by GPS to implement several capabilities
     such as listing constructs in the project explorer, highlighting
     the current block of code, going to the next or previous
     procedure, ...

`Format_Buffer'
     Name of a symbol in the specified shared library corresponding to a
     function that will indent and format a given buffer.

     This procedure is used to implement the auto indentation when
     hitting the <enter> key, or when using the format key on the
     current selection or the current line.

`Parse_Entities'
     Name of a symbol in the specified shared library corresponding to a
     function that will parse entities (e.g. comments, keywords, ...)
     of a given buffer. This procedure is used to highlight the syntax
     of a file, and overrides the `Context' node described below.

`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>
     
         <Engine>gpr</Engine>
         <Comment_Line>gpr_comment_line</Comment_Line>
       </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 except newlines, 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).

`%O'
     Used for recursive aliases expansion. This special character will
     expand the text seen before it in the current alias, after
     replacement of the parameters and possibly other recursive
     expansions. This is similar to pressing <control-o> (or any key
     you have defined for alias expansion) in the expanded form of the
     alias.

     You cannot expand an alias recursively when already expanding that
     alias. For instance, if the alias expansion for procedure contains
     procedure%O, the inner procedure will not be expanded.

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

The customization files described earlier can also contain aliases
definition. This can be used for instance to create project or system
wide aliases. All the customization files will be parsed to look for
aliases definition.

   However, all these customization files are considered as read-only
by GPS, and therefore cannot be edited through the graphical interface.
It is possible to override some of the aliases in your own custom files.

   There is one specific files, which must contain only aliases
definition. This is the file `$HOME/.gps/aliases'. Whenever you edit
aliases graphically, or create new ones, they are stored in this file,
which is the only one that GPS will ever modify automatically.

   The system files are loaded first, and aliases defined in them can be
overriden by the user-defined file.

   These files are standard customization files, *Note Customization
files::.  The specific XML tag to use is <alias>, one per new alias.
The following example contains a standalone customization file, but you
might wish to merge the <alias> tag in any other customization file.

   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.

   Here is an example of an alias file:

     <?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>

Adding support for new tools
============================

Support for external tools can be provided through GPS. Typically, this
would be done to specify different compilers, but it can also apply to
a wide variety of tools.

   GPS's support for external tools is enhancing with each release.
Typically, the following things need to be achieved to successfully use
a tool:

   * Specify its command line switches

   * Pass it the appropriate arguments depending on the current
     context, or       on user input

   * Spawn the tool

   * Optionally parse its result and act accordingly

   Each of these points is discussed in further sections. In all these
cases, most of the work can be done statically through XML
customization files.  These files have the same format as other
customization files (*note Customization files::), and the tool
descriptions are found in `<tool>' tags.

   This tag accepts the following attributes:

`name (mandatory)'
     This is the name of the tool. This is purely descriptive, and will
     appear throughout the GPS interface whenever this tool is
     referenced. This includes for instances the tabs of the switches
     editor.

`package (Default value is ide)'
     This optional attribute specifies which package should be used in
     the project to store information about this tool, in particular
     its switches. You cannot create new packages as you wish, and must
     use only existing packages. Most of the time the default value
     should be used, unless you are working with one of the predefined
     packages;

     If this attribute is set to "ide", then the switches cannot be set
     for a specific file, only at the project level. Support for
     file-specific switches currently requires modification of the GPS
     sources themselves.

`attribute (Default vluae is default_switches)'
     This optional attribute specifies the name of the attribute in the
     project which is used to store the switches for that tool.

`index (Default value is the tool name)'
     This optional attribute specifies what index is used in the
     project. This is mostly for internal use by GPS, and describes
     what index of the project attribute is used to store the switches
     for that tool.

   This tag accepts the following children, described in separate
sections:

`<switches>'
     (*note Defining tool switches::)

`<language>'
     (*note Defining supported languages::)

`<default-cmd-line>'
     (*note Defining the default command line::)

Defining supported languages
----------------------------

This is the language to which the tool applies.  There can be from no
to any number of such nodes for one `<tool>' tag.

   If no language is specified, the tool applies to all languages. In
particular, the switches editor page will be displayed for all
languages, no matter what languages they support.

   If at least one language is specified, the switches editor page will
only be displayed if that language is supported by the project.

     <tool name="My Tool" >
       <language>Ada</language>
       <language>C</language>
     </tool>

Defining the default command line
---------------------------------

It is possible to define the command line that should be used for a
tool when the user is using the default project, or hasn't overriden
this command line in the project.

   This is done through the `<initial-cmd-line>' tag, as a child of the
`<tool>' tag. Its value is the command line that would be passed to the
tool. This command line is parsed as usual, e.g. quotes are taken into
account to avoid splitting switches each time a space is encountered.

     <tool name="My tool" >
        <initial-cmd-line>-a -b -c</initial-cmd-line>
     </tool>

Defining tool switches
----------------------

The user has to be able to specify which switches to use with the tool.
If the tool is simply called through custom menus, you might want to
hard code some or all of the switches. However, in the general case it
is better to use the project properties editor, so that project-specific
switches can be specified.

   This is what GPS does by default for Ada, C and C++. You can find in
the GPS installation directory how the switches for these languages are
defined in an XML file. These provide extended examples of the use of
customization files.

   The switches editor in the project properties editor provides a
powerful interface to the command line, where the user can edit the
command line both as text and through GUI widgets.

   The switches are declared through the `<switches>' tag in the
customization file, which must be a child of a `<tool>' tag as described
above.

   This `<switches>' tag accepts the following attributes:

`lines (default value is 1)'
     The switches in the project properties editor are organized into
     boxes, each surrounded by a frame, optionally with a title. This
     attribute specifies the number of rows of such frames.

`columns (default value is 1)'
     This attribute specifies the number of columns of frames in the
     project properties page.

   This `<switches>' tag can have any number of child tag, among the
following. They can be repeated multiple times if you need several
check boxes.  For consistency, most of these child tags accept
attributes among the following:

`line (default value is 1)'
     This indicates the row of the frame that should contain the
     switch. See the description of `lines' above.

`column (default value is 1)'
     This indicates the column of the frame that should contain the
     switch. See the description of `columns' above.

`label'
     This is the label which is displayed in the graphical interface

`switch'
     This is the text that should be put on the command line if that
     switch is selected. Depending on its type, a variant of the text
     might be put instead, see the description of `combo' and `spin'
     below.  This switch shouldn't contain any space.

`tip (default value is empty)'
     This is the tooltip which describes that switch more extensively.
     It is displayed in a small popup window if the user leaves the
     mouse on top of the widget.

`min (default value is 1)'
     This attribute is used for `<spin>' tags, and indicates the minimum
     value authorized for that switch.

`max (default value is 1)'
     This attribute is used for `<spin>' tags, and indicates the maximum
     value authorized for that switch.

`default (default value is 1)'
     This attribute is used for `<spin>' tags. See the description
     below.

`noswitch (default is empty)'
     This attribute is only valid for `<combo>' tags, and described
     below.

`nodigit (default is empty)'
     This attribute is only valid for `<combo>' tags, and described
     below.

`value (mandatory)'
     This attribute is only valid for `<combo-entry>' tags.

   Here are the valid children for `<switches>':

`<title>'
     This tag, which accepts the `line' and `column' attributes, is used
     to give a name to a specific frame.  The value of the tag is the
     title itself. You do not have to specify a name, and this can be
     left to an empty value.

     Extra attributes for `<title>' are:

    `line-span (default value is 1)'
          This indicates how many rows the frame should span. If this
          is set to 0, then the frame is hidden from the user. See for
          instance the Ada or C switches editor.

    `column-span (default value is 1)'
          This indicates how many columns the frame should span. If
          this is set to 0, then the frame is hidden from the user. See
          for instance the Ada or C switches editor.

`<check>'
     This tag accepts the `line', `column', `label', `switch' and `tip'
     attributes. It creates a toggle button. When the latter is active,
     the text defined in the switch attribute is added as is to the
     command line. This tag doesn't have any value or child tags.

`<spin>'
     This tag acceps the `line', `column', `label', `switch', `tip',
     `min', `max' and `default' attributes.  This switch will add the
     contents of the `switch' attribute followed by the current numeric
     value of the widget to the command line. This is typically used to
     indicate indentation length for instance.  If the current value of
     the widget is equal to the `default' attribute, then nothing is
     added to the command line.

`<radio>'
     This tag accepts the `line' and `column' attributes. It groups any
     number of children, each of which is associated with its own
     switch. However, only one of the children can be selected at any
     given time.

     The children must have the tag `radio-entry'. This tag accepts the
     attributes `label', `switch' and `tip'.

`<field>'
     This tag accepts the `line', `column', `label', `switch' and `tip'
     attributes. This tag describes a text edition field, which can
     contain any text the user types. This text will be prefixed by the
     value of the `switch' attribute, and a space. If no text is
     entered in the field by the user, nothing is put on the command
     line.

     This tag accepts two extra attributes:

    `as-directory  (optional)'
          If this attribute is specified and set to "true", then an
          extra "Browse"    button is displayed, so that the user can
          easily select a directory.

    `as-file (optional)'
          This attribute is similar to `as-directory', but opens a
          dialog to    select a file instead of a directory. If both
          attributes are set to "true",    the user will select a file.

`<combo>'
     This tags accepts the `line', `column', `label', `switch', `tip',
     `noswitch' and `nodigit' attributes.

     The text inserted in the command line is the text from the `switch'
     attribute, concatenated with the text of the `value' attribute for
     the currently selected entry. If the value of the current entry is
     the same as that of the `nodigit' attribute, then only the text of
     the `switch' attribute is put on the command line. This is in fact
     necessary to interpret the gcc switch "-O" as "-O1".

     If the value of the current entry is that of the `noswitch'
     attribute, then nothing is put in the command line.

     The tag `<combo>' accepts any number of `combo-entry' children
     tags, each of which accepts the `label' and `value' attribute.

`<popup>'
     This tag accepts the `line', `column', `label', `lines' and
     `columns' attributes. This displays a simply button that, when
     clicked, displays a dialog with some extra switches. This dialog,
     just as the switches editor itself, is organizes into lines and
     columns of frames, the number of which is provided by the `lines'
     and `columns' attributes.

     This tag accepts any number of children, which are the same as the
     `<switches>' attribute itself.

`<dependency>'
     This tag is used to describe a relationship between two switches.
     It is used for instance when the "Debug Information" switch is
     selected for "Make", which forces it for the Ada compiler as well.

     It has its own set of attributes:

    `master-page master-switch'
          These two attributes define the switch that possibly forces a
          specific    setting on the slave switch. In our example, they
          would have the values    "Make" and "-g".     The switch
          referenced by these attributes must be of type `<check>'.

    `slave-page slave-switch'
          These two attributes define the switch which is acted upon by
          the master    switch. In our example, they would have the
          values "Ada" and "-g".     The switch referenced by these
          attributes must be of type `<check>'.

    `master-status slave-status'
          These two switches indicate which state of the master switch
          forces which    state of the slave-status. In our example,
          they would have the values    "on" and "on", so that when the
          make debug information is activated, the    compiler debug
          information is also activated. However, if the make debug
          information is not activated, no specific setup is forced for
          the compiler    debug information.

`<expansion>'
     This tag is used to describe how switches can be grouped together
     on the command line to keep it shorter. It is also used to define
     aliases between switches.

     It is easier to explain it through an example. Specifying the GNAT
     switch "-gnaty" is equivalent to specifying
     "-gnatyabcefhiklmnprst". This is in fact a style check switch,
     with a number of default values. But it is also equivalent to
     decomposing it into several switches, as in "-gnatya", "-gnaty3",
     "-gnatyb",... With this information, GPS will try to keep the
     command line length as short as possible, to keep it readable.

     Both these aspects are defined in a unique `<expansion>' tag, which
     accepts two attributes: `switch' is mandatory, and `alias' is
     optional. Alias contains the text "gnatyabcefhiklmnprst" in our
     example.

     It also accepts any number of `<entry>' children, each has a
     mandatory `switch' access. The set of all these children define
     the expanded equivalent of the switch. In our example, we need one
     `<entry>' child for "'gnaty3", one for "-gnatya",....

Executing external tools
------------------------

The user has now specified the default switches he wants to use for the
external tool. Spawning the external tool can be done in two ways:

   * From a menu

   * As a result of a key press

   Both cases are described in an XML customization file, as described
previously, and both are setup to execute what GPS calls an action,
i.e. a set of commands defined by the `<action>' tag.

Chaining commands
.................

   This action tag, as described previously, executes one or more
commands, which can either be internal GPS commands (written in any of
the scripting language supported by GPS), or external commands provided
by executables found on the PATH.

   The command line for each of these commands can either be hard-coded
in the customization file, or be the result of previous commands
executed as part of the same action. As GPS executes each command from
the action in turn, it saves its output on a stack as needed. If a
command line contains a special construct `%1', `%2'... then these
constructs will be replaced by the result of respectively the last
command executed, the previous from last command, and so on.

   Every time you execute a new command, it pushes the previous %1,
%2...  parameters one step further on the stack, so that they become
respectively %2, %3... and the output of that command becomes %1.

   The output of the previous commands is substituted exactly as is.
However, if the output is surrounded by quotes, they are ignored when a
substitution takes place, so you need to put them back if they are
needed. The reason for this behavior is so that for scripting languages
that systematically protect their output with quotes (simple or
double), these quotes are sometimes in the way when calling external
commands.

   If one of the commands in the action raises an error, the execution
of the action is stopped immediately, and no further command is
performed.

Saving open windows
...................

   Before launching the external tool, you might want to force GPS to
save all open files, the project.... This is done using the same
command GPS itself uses before starting a compilation. This command is
called `save_all', and takes one optional boolean argument which
specifies whether an interactive dialog should be displayed for the
user.

   Since this command aborts when the user presses cancel, you can
simply put it in its own `<shell>' command, as in:

     <action name="test save children">
       <shell>save_all 0</shell>
       <external>echo Run unless Cancel was pressed</external>
     </action>

Querying project switches
.........................

   Some GPS shell commands can be used to query the default switches
set by the user in the project file. These are
`get_tool_switches_as_string', `get_tool_switches_as_list', or, more
generally, `get_attribute_as_string' and `get_attribute_as_list'. The
first two require a unique parameter which is the name of the tool as
specified in the `<tool>' tag. This name is case-sensitive. The last
two commands are more general and can be used to query the status of
any attribute from the project. See their description by typing the
following in the GPS shell console window:

     help Project.get_attribute_as_string
     help Project.get_attribute_as_list

   The following is a short example on how to query the switches for
the tool "Find" from the project, *Note Full tool example::. It first
creates an object representing the current project, then passes this
object as the first argument of the `get_tool_switches_as_string'
command. The last external command is a simple output of these switches

     <action name="Get switches for Find">
       <shell>Project %p</shell>
       <shell>Project.get_tool_switches_as_string %1 Find </shell>
       <external>echo %1</external>
     </action>

Querying switches interactively
...............................

   Another solution to query the arguments for the tool is to ask the
user interactively.  The scripting languages provides a number of
solutions for these.

   They generally have their own native way to read input, possibly by
creating a dialog.

   In addition, the simplest solution is to use the predefined GPS
commands for this. These are the two functions:

`yes_no_dialog'
     This function takes a single argument, which is a question to
     display. Two buttons are then available to the user, "Yes" and
     "No". The result of this function is the button the user has
     selected, as a boolean value.

`input_dialog'
     This function is more general. It takes a minimum of two
     arguments, with no upper limit. The first argument is a message
     describing what input is expected from the user. The second, third
     and following arguments each correspond to an entry line in the
     dialog, to query one specific value (as a string). The result of
     this function is a list of strings, each corresponding to these
     arguments.

     From the GPS shell, it is only convenient to query one value at a
     time, since it doesn't have support for lists, and would return a
     concatenation of the values. However, this function is especially
     useful with other scripting languages.

Redirecting the command output
..............................

The output of external commands is send by default to the GPS console
window.  In addition, finer control can be exercised using the `output'
attribute of the `<external>' and `<shell>' tags.

   This attribute is a string that may take any value. Two values have
specific meanings:

`"none"'
     The output of the command, as well as the text of the command
     itself, will not be shown to the user at all.

`""'
     The output of the command is sent to the GPS console window,
     entitled "Messages".

`other values'
     A new window is created, the name of which is given by the
     attribute. If such a window already exists, it is cleared up
     before any of the command in the chain is executed. The output of
     the command, as well as the text of the command itself, are sent
     to this new window.

   This attribute can also be specified at the `<action>' tag level, in
which case it defines the default value for all `<shell>' and
`<external>' tags underneath. If it isn't specified for the action
itself, its default value will always be the empty string, i.e. output
is sent to the GPS console.

     <action name="ls current directory" output="default output" >
        <shell output="Current directory" >pwd</shell>
        <external output="Current directory contents" >/bin/ls </external>
     </action>

Processing the tool output
..........................

The output of the tool has now either been hidden or made visible to
the user in one or more windows.

   There are several additional things that can be done with this
output, for further integration of the tool in GPS.

  1. Parsing error messages Most often, external tools can display
     error messages for the user, and these are associated with
     specific files and locations in these files. This is for instance
     the way the GPS builder itself analyzes the output of `make'.

     This can be done for your own tools using the shell command
     `locations_parse'. This command takes several arguments, so that
     you can specify your own regular expression to find the file name,
     line number and so on in the error message. By default, it is
     configured to work seamlessly with error message of the forms:

          file:line: message
          file:line:column: message

     Please refer to the online help for this command to get more
     information.

     Here is a small example on how to run a make command and send the
     errors to the location window afterwards.

     For languages that support it, it is also recommended that you
     quote the argument with triple quotes, so that any special
     character (newlines, quotes, ...) in the output of the tool are
     not specially interpreted by GPS. Note also that you should leave
     a space at the end, in case the output itself ends with a quote.

          <action name="make example" >
             <external>make</external>
             <shell>locations_parse """%1 """ make_example</shell>
          </action>

  2. Auto-correcting errors GPS has support for automatically
     correcting errors for some of the languages.  You can get access
     to this auto-fixing feature through the `Codefix.parse' shell
     command, which takes the same arguments as for `locations_parse'.

     This will automatically add pixmaps to the relevant entries in the
     location window, and therefore `locations_parse' should be called
     first prior to calling this command.

     Errors can also be fixed automatically by calling the methods of
     the `Codefix' class. Several codefix sessions can be active at the
     same time, each of which is associated with a specific category.
     The list of currently active sessions can be retrieved through the
     `Codefix.sessions()' command.


Full tool example
-----------------

This section provides an example that defines a new tool. This is only
a short example, since Ada, C and C++ support themselves are provided
through such a file, available in the GPS installation.

   This example adds support for the "find" Unix utility, with a few
switches. All these switches are editable through the project
properties editor.

   It also adds a new action and menu. The action associated with this
menu gets the default switches from the currently selected project, and
then ask the user interactively for the name of the file to search.

     <?xml version="1.0" ?>
     <toolexample>
       <tool name="Find" >
         <switches columns="2" >
           <title column="1" >Filters</title>
           <title column="2" >Actions</title>
     
           <spin label="Modified less than n days ago" switch="-mtime-"
                 min="0" max="365" default="0" />
           <check label="Follow symbolic links" switch="-follow" />
     
           <check label="Print matching files" switch="-print" column="2" />
         </switches>
       </tool>
     
       <action name="action find">
         <shell>Project %p</shell>
         <shell>Project.get_tool_switches_as_string %1 Find </shell>
         <shell>input_dialog "Name of file to search" Filename</shell>
         <external>find . -name %1 %2</external>
       </action>
     
       <Submenu>
         <Title>External</Title>
          <menu action="action find">
            <Title>Launch find</Title>
         </menu>
       </Submenu>
     </toolexample>

Defining New Styles and Key Bindings
====================================

In addition to the GPS specific mechnisms described previousely, GPS
can be configured through the low level Gtk+ mechanism of `RC files'.

   As more customization capabilities are added in GPS, this mechanism
will become less useful and built-in GPS capabilities should be
prefered.

   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 foreground of visual objects displaying
     editable text (e.g. source editors), using base for the background
     color.

`text[state] = color'
     Sets the color used for the background of visual objects
     displaying editable text, for instance the text editor in GPS.

`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,...

   These languages all have a separate console associated with them,
which you can open from the `Tools' menu. In each of these console, GPS
will display a prompt, at which you can type interactive commands.
These console provide completion of the command names through the <tab>
key.

   For instance, in the GPS shell console you can start typing
     GPS> File

   then press the <tab> key, which will list all the functions whose
name starts with "File".

   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'

   See the section *Note Customizing the Menu and Tool Bar:: on how to
bind key shortcuts to shell commands.

Scripts and GPS actions
-----------------------

There is a strong relationship between GPS actions, as defined in the
customization files, and scripting languages.

   Actions can be bound to menus and keys through the customization
files or the `Edit->Key shortcuts' dialog.

   These actions can execute any script command, *Note Defining
Actions::. This is done through the `<shell>' XML tag.

   But the opposite is also true. From a script, you can execute any
action registered in GPS. This can for instance be used to split
windows, highlight lines in the editor,... when no equivalent shell
function exists. This can also be used to execute external commands, if
the scripting language doesn't support this in an easy manner.

   Such calls are made through a call to `execute_action', as in the
following example:

     execute_action "Split horizontally"

   The list of actions known to GPS can be found through the `Edit->Key
shortcuts' dialog. Action names are case sensitive.

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

   Arguments to commands can, but need not, be quoted. If they don't
contain any space, double-quote ('"') or newline characters, you do not
need to quote them. Otherwise, you should surround them with
double-quotes, and protect any double-quote part of the argument by
preceding it with a backslash.

   There is another way to quote a command: use three double-quotes
characters in a row. Any character loses its special meaning until the
next three double-quotes characters set. This is useful if you do not
know in advance the contents of the string you are quoting.

     locations_parse """%1 """ category_name

   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] [-P project-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 can be absolute or relative pathnames.
     If you prepend a file name with '=', this file will be
     searched anywhere 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.

`GPS_CUSTOM_PATH'
     Contains a list of directories to search for custom files. See
     *Note Customizing the Menu and Tool Bar:: 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.  When GPS is running, it
     will create a file named `log.<pid>', where `<pid>' is the GPS
     process id, so that multiple GPS sessions do not clobber each
     other's log. In case of a successful session, this file is renamed
     `log' when exiting; in case of an unexpected exit (a bug box will
     be displayed), the log file is kept under its original name.

     Note that the name of the log file is configured by the
     `traces.cfg' file.

`$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 menu shortcuts 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/keys.xml'
     Contains all the key bindings for the actions defined in GPS or in
     the custom files. This only contains the key bindings overridden
     through the key shortcuts editor (see *Note The Key Manager
     Dialog::).

`$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
     More->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.<pid>'.

     This file is created automatically when it does not exist. When
     upgrading to a new version of GPS, it is recommended to remove it
     since its contents may change from version to version.

`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/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/language'
     This directory contains sources showing how to provide a shared
     library to dynamically define a new language. See *Note Adding
     Support for New Languages::.

`prefix/doc/gps/examples/tutorial'
     This directory contains the sources used by the GPS tutorial.

`prefix/share/gps/customize'
     Directory containing files with system-wide customizations (see
     *Note Adding Support for New Languages:: and  *Note Defining Text
     Aliases::).

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

   In case GPS generates a bug box, the log file will be kept under a
separate name (`$HOME/.gps/log.<pid>' so that it does not get erased by
further sessions. Be sure to include the right log file when reporting
a bug box.

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.

`My project have several files with the same name. How can I import it in GPS?'
     GPS's projects do not allow implicit overriding of sources file,
     i.e.  you cannot have multiple times the same file name in the
     project hierarchy. The reason is that GPS needs to know exactly
     where the file is, and cannot reliably guess which occurrence to
     use.

     There are several solutions to handle this issue:

        * Use scenario variables in the project

          The idea is that you define various scenarios in your project
          (For instance compiling in "debug" mode or "production"
          mode), and change the source directories depending on this
          setup.  Such projects can be edited directly from GPS (in the
          project properties editor, this is the right part of the
          window, as described in this documentation). On top of the
          project explorer (left part of the GPS main window), you have
          a combo box displayed for each of the variable, allowing a
          simple switch between scenarios depending on what you want to
          build.

        * Use extending projects

          These projects cannot currently be created through GPS, so
          you will need to edit them by hand. See the GNAT user's guide
          for more information on extending projects.

          The idea behind this approach is that you can have a local
          overriding of some source files from the common build/source
          setup (if you are working on a small part of the whole
          system, you may not want to have a complete copy of the code
          on your local machine).

        * Put all duplicate files in the same project

          There is one specific case where a project is allowed to have
          duplicate source files: if the list of source directories is
          specified explicitely. All duplicate files must be in the
          same project. With these conditions, there is no ambiguity
          for GPS and the GNAT tools which file to use, and the first
          file found on the source path is the one hidding all the
          others. GPS only shows the first file.

          You can then have a scenario variable that changes the order
          of source directories to give visibility on one of the other
          duplicate files.


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''.
<action>:
          See ``Defining Actions''.
<alias>:
          See ``Defining Text Aliases''.
<button>:
          See ``Adding tool bar buttons''.
<check>:
          See ``Defining tool switches''.
<combo-entry>:
          See ``Defining tool switches''.
<combo>:
          See ``Defining tool switches''.
<contextual>:
          See ``Adding contextual menus''.
<dependency>:
          See ``Defining tool switches''.
<entry>:
          See ``Defining tool switches''.
<expansion>:
          See ``Defining tool switches''.
<external>:
          See ``Defining Actions''.
<field>:
          See ``Defining tool switches''.
<filter> <1>:
          See ``Filtering actions''.
<filter>:
          See ``Defining Actions''.
<filter_and>:
          See ``Filtering actions''.
<filter_or>:
          See ``Filtering actions''.
<initial-cmd-line>:
          See ``Defining the default command line''.
<key>:
          See ``Binding actions to keys''.
<language>:
          See ``Defining supported languages''.
<Language>:
          See ``Adding Support for New Languages''.
<menu>:
          See ``Adding new menus''.
<popup>:
          See ``Defining tool switches''.
<radio-entry>:
          See ``Defining tool switches''.
<radio>:
          See ``Defining tool switches''.
<shell>:
          See ``Defining Actions''.
<spin>:
          See ``Defining tool switches''.
<submenu>:
          See ``Adding new menus''.
<switches>:
          See ``Defining tool switches''.
<title> <1>:
          See ``Defining tool switches''.
<title>:
          See ``Adding new menus''.
<tool>:
          See ``Adding support for new tools''.
<vsearch-pattern>:
          See ``Defining new search patterns''.
a2ps:
          See ``The Preferences Dialog''.
action <1>:
          See ``Defining Actions''.
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 ``Contextual Menus for Source Navigation''.
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 ``Macro arguments''.
arguments:
          See ``The Debug Menu''.
as-directory:
          See ``Defining tool switches''.
as-file:
          See ``Defining tool switches''.
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''.
background tasks:
          See ``The Task Manager''.
block:
          See ``General Information''.
block folding:
          See ``The Preferences Dialog''.
block highlighting:
          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 ``Compilation/Build''.
build <2>:
          See ``The Status Line''.
build <3>:
          See ``The Locations Tree''.
build:
          See ``The Messages Window''.
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 ``Contextual Menus for Source Navigation''.
call stack <1>:
          See ``The Call Stack Window''.
call stack:
          See ``The Debug Menu''.
called by:
          See ``Contextual Menus for Source Navigation''.
calls:
          See ``Contextual Menus for Source Navigation''.
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''.
Codefix.parse:
          See ``Processing the tool output''.
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:
          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 ``Contextual Menus for Source Navigation''.
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 line <1>:
          See ``Using the Source Editor when Debugging''.
current line:
          See ``General Information''.
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:
          See ``General Information''.
dependency:
          See ``The Preferences Dialog''.
dependency browser:
          See ``Dependency Browser''.
description:
          See ``Defining Actions''.
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 <1>:
          See ``Moving Windows''.
drag-n-drop:
          See ``The Project Explorer''.
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''.
End Of Statement:
          See ``The Navigate Menu''.
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 ``Macro arguments''.
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''.
execute_action:
          See ``Scripts and GPS actions''.
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''.
export:
          See ``General Issues''.
external:
          See ``Defining Actions''.
external editor <1>:
          See ``The Preferences Dialog''.
external editor:
          See ``Using an External Editor''.
external tool:
          See ``Adding support for new tools''.
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 <1>:
          See ``Defining Actions''.
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 ``Contextual Menus for Source Navigation''.
find all reads:
          See ``Contextual Menus for Source Navigation''.
find all references <1>:
          See ``Contextual Menus for Source Navigation''.
find all references:
          See ``The Navigate Menu''.
find all writes:
          See ``Contextual Menus for Source Navigation''.
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''.
fold:
          See ``Menu Items''.
font:
          See ``The Preferences Dialog''.
ftp:
          See ``Remote Files''.
generate body:
          See ``Menu Items''.
get_attribute_as_list:
          See ``Querying project switches''.
get_attribute_as_string:
          See ``Querying project switches''.
get_tool_switches_as_list:
          See ``Querying project switches''.
get_tool_switches_as_string:
          See ``Querying project switches''.
gif <1>:
          See ``Files''.
gif:
          See ``Adding tool bar buttons''.
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 ``Contextual Menus for Source Navigation''.
goto body:
          See ``The Navigate Menu''.
goto declaration <1>:
          See ``Contextual Menus for Source Navigation''.
goto declaration:
          See ``The Navigate Menu''.
goto file spec/body <1>:
          See ``Contextual Menus for Source Navigation''.
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_CUSTOM_PATH:
          See ``Environment Variables''.
GPS_DOC_PATH:
          See ``Environment Variables''.
GPS_HOME:
          See ``Environment Variables''.
gps_index.xml:
          See ``Adding New Help Files''.
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''.
image:
          See ``General Issues''.
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''.
input_dialog:
          See ``Querying switches interactively''.
integrated help:
          See ``Integrated Help''.
interactive command <1>:
          See ``Defining Actions''.
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 ``Adding tool bar buttons''.
key <1>:
          See ``Binding actions to keys''.
key <2>:
          See ``Customizing the Menu and Tool Bar''.
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 shortcuts:
          See ``Menu Items''.
key theme:
          See ``The Preferences Dialog''.
kill:
          See ``The Debug Menu''.
languages:
          See ``Supported Languages''.
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''.
locations_parse:
          See ``Processing the tool output''.
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 ``Macro arguments''.
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''.
menus:
          See ``Adding new menus''.
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''.
namespace:
          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 Subprogram:
          See ``The Navigate Menu''.
next tag:
          See ``The Navigate Menu''.
nexti:
          See ``The Debug Menu''.
normalization of projects:
          See ``Description of the Projects''.
object directory <1>:
          See ``The Project Wizard''.
object directory:
          See ``Description of the Projects''.
on-failure:
          See ``Defining Actions''.
on-failure-lang:
          See ``Defining Actions''.
opaque:
          See ``The Preferences Dialog''.
open:
          See ``Menu Items''.
options:
          See ``Command Line Options''.
output:
          See ``Redirecting the command output''.
overloaded:
          See ``Support for Cross-References''.
paste <1>:
          See ``Using the Clipboard''.
paste:
          See ``Menu Items''.
patch:
          See ``The Preferences Dialog''.
png <1>:
          See ``Adding tool bar buttons''.
png:
          See ``General Issues''.
predefined patterns:
          See ``Defining new search patterns''.
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 Subprogram:
          See ``The Navigate Menu''.
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 ``Contextual Menus for Source Navigation''.
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 files:
          See ``Remote Files''.
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''.
rsh:
          See ``Remote Files''.
rsync:
          See ``Remote Files''.
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''.
save_all:
          See ``Saving open windows''.
saving:
          See ``Saving Files''.
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''.
separate unit:
          See ``Support for Cross-References''.
shell <1>:
          See ``Defining Actions''.
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''.
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''.
Splitting:
          See ``Splitting Windows''.
ssh:
          See ``Remote Files''.
Start Of Statement:
          See ``The Navigate Menu''.
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 ``Macro arguments''.
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''.
task manager:
          See ``The Task Manager''.
tasks:
          See ``The Task Manager''.
telnet:
          See ``Remote Files''.
terminate:
          See ``The Debug Menu''.
testing:
          See ``Menu Items''.
text files:
          See ``Supported Languages''.
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 ``Adding tool bar buttons''.
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''.
unfold:
          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 ``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 ``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''.
warning index:
          See ``The Preferences Dialog''.
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 ``Integrating existing build procedures with the GPS build system''.
Windows <5>:
          See ``Using an External Editor''.
Windows <6>:
          See ``Menu Items''.
Windows <7>:
          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 ``Adding tool bar buttons''.
yank <1>:
          See ``Using the Clipboard''.
yank:
          See ``Menu Items''.
yes_no_dialog:
          See ``Querying switches interactively''.
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
  The Task Manager

Integrated Help
  The Help Menu
  Adding New Help Files

Multiple Document Interface
  Selecting Windows
  Closing Windows
  Maximized and Iconified Windows
  Docked Windows
  Splitting 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
  Saving Files
  Remote Files

Source Navigation
  Support for Cross-References
  The Navigate Menu
  Contextual Menus for Source Navigation

Project Handling
  Description of the Projects
    Project files and GNAT tools
    Contents of project files
  Supported Languages
  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
  Upgrading from GVD to GPS
    Command Line Switches
    Menu Items
    Tool Bar Buttons
    Key Short Cuts
    Contextual Menus
    File Explorer
    Advantages of GPS

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
  The Key Manager Dialog
  Customizing the Menu and Tool Bar
    Redefining key bindings
    Customization files
    Defining Actions
    Macro arguments
    Filtering actions
      The filters tags
    Adding new menus
    Adding contextual menus
    Adding tool bar buttons
    Binding actions to keys
    Defining new search patterns
    Full example
  Adding Support for New Languages
  Defining Text Aliases
    Aliases files
  Adding support for new tools
    Defining supported languages
    Defining the default command line
    Defining tool switches
    Executing external tools
      Chaining commands
      Saving open windows
      Querying project switches
      Querying switches interactively
      Redirecting the command output
      Processing the tool output
    Full tool example
  Defining New Styles and Key Bindings
    Toplevel declarations
    Defining new styles
    Defining new key bindings
  Scripting GPS
    Scripts
    Scripts and GPS actions
    The GPS Shell

Environment
  Command Line Options
  Environment Variables
  Files
  Reporting Suggestions and Bugs
  Solving Problems

Index


