\input texinfo   @c -*-texinfo-*-
@input texiplus

@c %**start of header
@setfilename gps.info
@settitle Using the GNAT Programming System
@syncodeindex fn cp

@set GPS
@set GPSVersion 1.2.2

@titlepage

@flushleft
@title{Using GPS}
@end flushleft
@flushright
 @titlefont{The GNAT Programming System}
@end flushright
@subtitle Version @value{GPSVersion}
@subtitle Document revision level 1.186.2.12
@subtitle Date: 2003/06/11 09:15:34
@author ACT Europe

@page
@vskip 0pt plus 1filll

Copyright @copyright{} 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.

@end titlepage

@ifnotinfo
@contents
@end ifnotinfo

@ifinfo
@node Top, Introduction, (dir), (dir)
@top Using the GNAT Programming System

Using the GNAT Programming System

GPS, the GNAT Programming System

Version @value{GPSVersion}

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

Copyright @copyright{} 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.

@menu
* Introduction::
* Description of the Main Windows::
* Integrated Help::
* Multiple Document Interface::
* Editing Files::
* Source Navigation::
* Project Handling::
* Searching and Replacing::
* Compilation/Build::
* Source Browsing::
* Debugging::
* Version Control System::
* Tools::
* Working in a Cross Environment::
* Customizing and Extending GPS::
* Environment::
@c * Python Commands::

@detailmenu

 --- The Detailed Node Listing ---

Description of the main windows
* The Welcome Dialog::
* The Menu Bar::
* The Tool Bar::
* The Work Space::
* The Project Explorer::
* The Messages Window::
@c * The Shell and Python Windows::
* The Shell Window::
* The Locations Tree::
* The Status Line::

Integrated Help
* The Help Menu::
* Adding New Help Files::

Multiple Document Interface
* Selecting Windows::
* Closing Windows::
* Maximized and Iconified Windows::
* Docked Windows::
* Floating Windows::
* Moving Windows::

Editing Files
* General Information::
* Editing Sources::
* The File Selector::
* Menu Items::
* Using an External Editor::
* Using the Clipboard::

Source Navigation
* Support for Cross References::
* The Navigate Menu::
* Source Navigation Contextual Menus::

Project Handling
* Description of the Projects::
* Scenarios and Configuration Variables::
* The Project Explorer (Editing Projects)::
* The Project Menu::
* The Project Wizard::
* The Project Properties Editor::
* The Switches Editor::
* The Project Browser::

Searching and Replacing

Compilation/Build
* The Build Menu::
@c * Multi-language Build::
* Integrating existing build procedures with the GPS build system::

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

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

Version Control System
* The VCS Explorer::
* The VCS Menu::
* The Version Control Contextual Menu::

Tools
* The Tools Menu::
* Visual Comparison::
* Code Fixing::

Working in a Cross Environment
* Customizing your Projects::
* Debugger Issues::

Customizing and Extending GPS
* The Preferences Dialog::
* Customizing the Menu and Tool Bar::
* Adding Support for New Languages::
* Defining Text Aliases::
* Defining New Styles and Key Bindings::
* Scripting GPS::

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

@end detailmenu
@end menu
@end ifinfo

@c --------------------------------------------------------------------
@node Introduction
@chapter Introduction
@cindex introduction
@c --------------------------------------------------------------------

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

@cindex HTML
@cindex help
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@dots{};
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.

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

@cindex editor
@cindex emacs
GPS also integrates with existing editors such as Emacs and Vi, see
@ref{Using an External Editor}.

@c --------------------------------------------------------------------
@node Description of the Main Windows
@chapter Description of the Main Windows
@cindex main windows
@c --------------------------------------------------------------------

@menu
* The Welcome Dialog::
* The Menu Bar::
* The Tool Bar::
* The Work Space::
* The Project Explorer::
* The Messages Window::
@c * The Shell and Python Windows::
* The Shell Window::
* The Locations Tree::
* The Execution Window::
* The Status Line::
@end menu

@c --------------------------------------------------------------------
@node The Welcome Dialog
@section The Welcome Dialog
@cindex welcome dialog
@c --------------------------------------------------------------------

@iftex
@cindex screen shot
@image{welcome, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{welcome}
@end ifhtml

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

@table @b
@item Start with default project in directory
@cindex project
If you select this option and click on the @code{OK} button, GPS will create a
default internal project with the following properties:

@cindex Ada
@cindex GNAT
  The project supports Ada files only, using the default GNAT
  naming scheme: @code{.ads} for spec files, @code{.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 @code{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.

@item Create new project with wizard
@cindex project
Selecting this option and clicking on the @code{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 @ref{The Project Wizard} for more details on the project wizard.

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

@item 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
@code{-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 @code{Edit->Preferences}.
@cindex preferences
@xref{The Preferences Dialog}.

@item Quit
If you click on this button, GPS will terminate immediately.
@end table

@cindex command line
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.

@c --------------------------------------------------------------------
@node The Menu Bar
@section The Menu Bar
@cindex menu bar
@c --------------------------------------------------------------------

@noindent
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, @dots{}). Contextual menus
pop up when the right mouse button is clicked.

The menu bar gives access to the following items:

@table @b

@item File
@xref{The File Menu}.

@item Edit
@xref{The Edit Menu}.

@item Navigate
@xref{The Navigate Menu}.

@item VCS
@xref{The VCS Menu}.

@item Project
@xref{The Project Menu}.

@item Build
@xref{The Build Menu}.

@item Debug
@xref{The Debug Menu}.

@item Tools
@xref{The Tools Menu}.

@item Window
@xref{Multiple Document Interface}.

@item Help
@xref{The Help Menu}.
@end table

@c --------------------------------------------------------------------
@node The Tool Bar
@section The Tool Bar
@cindex tool bar
@c --------------------------------------------------------------------

@noindent
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;
@cindex clipboard
cut to clipboard, copy to clipboard, paste from clipboard;
go to previous/next location;
@cindex debugger
start/continue the debugging session, step/next execution, finish
current procedure.

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

@c --------------------------------------------------------------------
@node The Work Space
@section The Work Space
@cindex work space
@cindex MDI
@cindex Multiple Document Interface
@c --------------------------------------------------------------------

The whole work space is based on a multiple document interface,
@xref{Multiple Document Interface}.

@c --------------------------------------------------------------------
@node The Project Explorer
@section The Project Explorer
@cindex project explorer
@cindex project
@c --------------------------------------------------------------------

@noindent
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 @code{Project} menu items.

@subsection The explorer views
@cindex explorer views

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

The following screen shot displays the two pages side-by-side: on the
left, the @code{Project View}, and on the right the @code{File View}.

@iftex
@cindex screen shot
@image{explorer-views, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{explorer-views}
@end ifhtml

@cindex interactive search
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 @key{Ctrl-i}. See @ref{Interactive Search}
for more details.

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

@table @b
@item projects
@cindex project view
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 @code{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
@code{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.

@cindex Show flat view
This display is activated through the contextual menu entry
@code{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.

@item directories
@cindex directory
@cindex Windows
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 @code{Project View}, or directly mimicking their
physical organization on the disk (including Windows drives) in the
@code{File View}.

@cindex Show absolute paths
In the @code{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 @code{Show absolute
paths} contextual menu.

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

@item files
@cindex file
@cindex file view
The source files themselves are stored in the directories, and
displayed under the corresponding nodes. Note that in the
@code{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.

@cindex Show files from project only
The @code{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 @code{Show files from project only}.

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

@item entities
@cindex entity
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,@dots{}

@end table

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

@cindex search
@cindex find
If you open the search dialog through the @code{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.

@cindex explorer
@cindex locate in explorer
A contextual menu, named @code{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 @code{Dependency Browser}.


@subsection The configuration variables
@cindex configuration variable
@cindex project variable
@cindex variable

@cindex GNAT
@cindex project file
@cindex project
@noindent
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 @code{Project View}. These variables are called
@code{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

@cindex project view
New variables can be added through the contextual menu @code{Add
Configuration Variable} in the @code{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.

@c --------------------------------------------------------------------
@node The Messages Window
@section The Messages Window
@cindex messages
@cindex messages window
@c --------------------------------------------------------------------

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

@iftex
@cindex screen shot
@image{messages, 11.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{messages}
@end ifhtml

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

@cindex execution window
@cindex execution
@cindex shell window
@cindex shell
For an input/output window, see @ref{The Execution Window} and also
@c @ref{The Shell and Python Windows}.
@ref{The Shell Window}

@c --------------------------------------------------------------------
@c @node The Shell and Python Windows
@c @section The Shell and Python Windows
@node The Shell Window
@section The Shell Window
@cindex shell
@cindex shell window
@c @cindex python window
@cindex interactive command
@cindex command
@c --------------------------------------------------------------------

@noindent
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.

@c Some of these windows, especially the python window, might not be
@c visible in your version of GPS, if GPS wasn't compiled with the
@c support for that specific scripting language.

See @ref{Scripting GPS} for more information on using
scripting languages within GPS.

@iftex
@cindex screen shot
@image{shell-window, 11.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{shell-window}
@end ifhtml

@cindex key
You can use the @key{up} and @key{down} keys to navigate through the
history of commands.

@c --------------------------------------------------------------------
@node The Locations Tree
@section The Locations Tree
@cindex location
@cindex locations tree
@c --------------------------------------------------------------------

@cindex search
@cindex compilation
@cindex build
@noindent
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).

@iftex
@cindex screen shot
@image{locations-view, 11.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{locations-view, 12.7cm}
@end ifhtml

@cindex category
@cindex file
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.

@cindex key
@cindex menu
To navigate through the next and previous location (also called @code{Tag}),
you can use the menu items @code{Navigate->Previous Tag} and
@code{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 @ref{Code Fixing} for more information on how to make advantage
of this icon.

@c --------------------------------------------------------------------
@node The Execution Window
@section The Execution Window
@cindex execution
@cindex execution window
@c --------------------------------------------------------------------

@cindex run
@noindent
Each time a program is launched using the menu @code{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.

@cindex key
@cindex menu
To close an execution window, click on the cross icon on the top right corner
of the window, or use the menu @code{File->Close}, or the menu
@code{Window->Close} or the key binding @key{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.

@c --------------------------------------------------------------------
@node The Status Line
@section The Status Line
@cindex status
@cindex status line
@cindex status bar
@cindex progress bar
@c --------------------------------------------------------------------

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

@cindex messages
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 @code{Messages} window.

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

@c --------------------------------------------------------------------
@node Integrated Help
@chapter Integrated Help
@cindex integrated help
@cindex help
@cindex HTML
@c --------------------------------------------------------------------

@menu
* The Help Menu::
* Adding New Help Files::
@end menu

@noindent
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 @code{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 @code{Help} window
when not using it. You can reopen this window at any time using the
@code{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.

@node The Help Menu
@section The Help Menu
@noindent
The Help menu item provides the following entries:

@table @b
@item Contents
This opens a special HTML file that contains links for all the
documentation files currently registered in GPS, @xref{Adding New Help Files}.

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

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

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

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

@iftex
@cindex screen shot
@image{about, 8.7cm} 
@end iftex

@ifhtml 
@cindex screen shot
@image{about}
@end ifhtml

@end table

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.

@node Adding New Help Files
@section Adding New Help Files
@noindent

GPS will search for the help files in the list of directories set in
the environment variable @code{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 @code{<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 @code{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 @file{gps} itself on Unix systems.

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

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

There should be one @code{<file>} tag per help file. This tag contains
four children tags:

@table @b
@item 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
@code{GPS_DOC_PATH}.

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

@smallexample
  <name>file#anchor</name>
@end smallexample

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

@item category
This is used in the @code{Help->Contents} menu to organize all the
documentation files.

@item 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 @code{"/"}. 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
@code{Help->Contents} menu

@end table


@c --------------------------------------------------------------------
@node Multiple Document Interface
@chapter Multiple Document Interface
@cindex MDI
@cindex Multiple Document Interface
@cindex window manager
@cindex work space
@c --------------------------------------------------------------------

@menu
* Selecting Windows::
* Closing Windows::
* Maximized and Iconified Windows::
* Docked Windows::
* Floating Windows::
* Moving Windows::
@end menu


@noindent
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,@dots{} 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.

@cindex iconify
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.

@c --------------------------------------------------------------------
@node Selecting Windows
@section Selecting Windows
@cindex window selection
@c --------------------------------------------------------------------

@noindent
At any time, there is only one selected window in GPS (the @b{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 @code{Window}.

Alternatively, windows can be selected with the keyboard. By default,
the selection key is @key{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
@key{Alt} pressed while pressing other keys than @key{Tab}, this
will modify the current filter. From then on, pressing
@key{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
@file{unit1.adb} and @file{file.adb}, pressing @key{t} will only leave
@file{unit1.adb} selectable.

@c --------------------------------------------------------------------
@node Closing Windows
@section Closing Windows
@cindex close
@c --------------------------------------------------------------------

@cindex title bar
@noindent
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.

@iftex
@cindex screen shot
@image{mdi-title-bar, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{mdi-title-bar}
@end ifhtml

Alternatively, you can also select the window by clicking anywhere in
its title bar, and then select the menu @code{Window->Close}

@c --------------------------------------------------------------------
@node Maximized and Iconified Windows
@section Maximized and Iconified Windows
@cindex maximized
@cindex iconified
@c --------------------------------------------------------------------

@noindent
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 @ref{Docked Windows}.
The third area is the one that provides the most flexibility:

@table @b

@item 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.

@iftex
@cindex screen shot
@image{mdi-scroll-tabs, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{mdi-scroll-tabs}
@end ifhtml

@cindex menu
You can go back to this maximized state in two ways: either select the
menu @code{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.


@item unmaximized windows
@cindex unmaximized
@cindex menu
As opposed to putting all the windows inside a notebook, GPS can also
let you organize them freely when they are unmaximized. Select the
menu @code{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:
@cindex menu

@table @code
@item Window->Cascade
@cindex 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

@item Window->Tile Horizontally
@cindex title
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.

@iftex
@cindex screen shot
@image{mdi-tile-horizontal, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{mdi-tile-horizontal}
@end ifhtml

@item Window->Tile Vertically
@cindex title
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.

@iftex
@cindex screen shot
@image{mdi-tile-vertical, 9.5cm}
@end iftex

@ifhtml
@cindex screen shot
@image{mdi-tile-vertical}
@end ifhtml

@end table


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

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

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

@iftex
@cindex screen shot
@image{mdi-icons, 9.5cm}
@end iftex

@ifhtml
@cindex screen shot
@image{mdi-icons}
@end ifhtml

@end table

@c --------------------------------------------------------------------
@node Docked Windows
@section Docked Windows
@cindex docked
@cindex docked window
@cindex work space
@c --------------------------------------------------------------------

@noindent
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
@b{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,@dots{} Although you can not control this initial position, it is
possible to change it later on (@ref{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).

@cindex handle
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
@code{Edit->Preferences}) to indicate that you want the resizing to be
opaque, which might give more intuitive results.
@cindex preferences

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

@cindex menu
A simple way to dock a window is to select it, and then select the
menu @code{Window->Docked}. We will see in @ref{Moving Windows} that
there is a more intuitive way to do the same thing.

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

@c --------------------------------------------------------------------
@node Floating Windows
@section Floating Windows
@cindex floating
@cindex top level
@c --------------------------------------------------------------------

@noindent
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,@dots{}).

GPS is fully compatible with this behavior, since windows can also be
@b{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 @code{Window->Floating}. The window will then
be detached, and can be moved anywhere on your screen, even outside of
GPS's main window.

@cindex menu
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 @code{Window}, and then select @code{Window->Floating}.

@cindex preferences
The second method assumes that the preference @b{Destroy Floats} in
the menu @code{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.

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

This special mode is activated through a preference (menu
@code{Edit->Preferences}). This preference is entitled @b{All
Floating}.


@c --------------------------------------------------------------------
@node Moving Windows
@section Moving Windows
@cindex moving
@c --------------------------------------------------------------------

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

@cindex menu
In all cases, the changes are done either through the buttons in the
title bar or through the menu @code{Window}.

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

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

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

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

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

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

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

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

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

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

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

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

@end table


@c --------------------------------------------------------------------
@node Editing Files
@chapter Editing Files
@cindex editing
@c --------------------------------------------------------------------

@menu
* General Information::
* Editing Sources::
* The File Selector::
* Menu Items::
* Using an External Editor::
* Using the Clipboard::
@end menu

@c --------------------------------------------------------------------------
@node General Information
@section General Information
@c --------------------------------------------------------------------------

@noindent
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.

@iftex
@cindex screen shot
@image{source-editor, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{source-editor}
@end ifhtml

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

@table @b
@item A title bar
Showing the full name of the file including path information.

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

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

@item 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. @i{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 @i{writable} and @i{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:

@table @i
@item Unmodified
The file has not been modified since the file has been loaded or saved.

@item 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 @i{Unmodified}.

@item Saved
The file has been saved and not modified since.

@end table

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

@item A contextual menu
Displayed when you right-click on any area of the source editor.
See in particular @ref{Source Navigation Contextual Menus}
for more details.

@item 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 @ref{The Preferences Dialog} for a list of
settings that can be customized.

@item Automatic indentation
@cindex indentation
When enabled, lines are automatically indented each time you press the
@key{Enter} key, or by pressing the indentation key.
The indentation key is @key{Ctrl-Tab} by default, and can be changed in the
preferences dialog, @xref{The Preferences Dialog}.

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

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

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

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

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

You can disable the automatic pop up of tool tips in the Editor section of
the preferences dialog. @xref{The Preferences Dialog}.

@item Word completion
@cindex 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 @key{Ctrl-/} key
combination (customizable through the preferences dialog) after a partial
word: the next possible completion will be inserted in the editor. Typing this
key again will cycle through the list of possible completions.

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

@item Delimiter highlighting
@cindex delimiter
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 @key{Ctrl-'} key,
that can be configured in the preferences. Typing twice on this key will move
the cursor back to its original position.

@item Current line highlighting
@cindex current
You can configure the editor to highlight the current line with a certain
color. @xref{The Preferences Dialog}.
 
@item Auto save
@cindex auto save
You can configure the editor to periodically save modified files.
See @ref{autosave delay} for a full description of this capability.

@end table

@cindex emacs
GPS also integrates with existing third party editors such as
@code{Emacs}. @xref{Using an External Editor}.

@c --------------------------------------------------------------------------
@node Editing Sources
@section Editing Sources
@cindex editing
@cindex source file
@c --------------------------------------------------------------------------

@subsection Key bindings
@cindex key
@noindent
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
@ref{Defining Text Aliases} and @ref{Defining new key bindings}.

@table @b
@item Common key bindings
@cindex key

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

@item Ctrl-x / Shift-delete
Cut to clipboard

@item Ctrl-c / Ctrl-insert
Copy to clipboard

@item Ctrl-v / Shift-insert
Paste from clipboard

@item Ctrl-s
Save file to disk

@item Ctrl-z
Undo previous insertion/deletion

@item Ctrl-r
Redo previous insertion/deletion

@item Insert
Toggle overwrite mode

@item Ctrl-a
Select the whole file

@item Home / Ctrl-Pgup
Go to the beginning of the line

@item End / Ctrl-Pgdown
Go to the end of the line

@item Ctrl-Home
Go to the beginning of the file

@item Ctrl-End
Go to the end of the file

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

@item 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.

@item Ctrl-delete
Delete end of the current word.

@item Ctrl-backspace
Delete beginning of the current word.

@end table

@item Emacs key bindings
@cindex emacs
@cindex key
The following key bindings are activated if you select the @i{Emacs} key theme
in the preferences dialog (@xref{The Preferences Dialog}.), and may override
common keys (e.g. @key{Ctrl-a}).

@table @key
@item Ctrl-b
Move the cursor one character on the left

@c @item Ctrl-f  overridden by find

@c @item Alt-b  overridden by Build menu

@item Shift-Alt-b
Select the previous word (backward).

@c @item Alt-f  overridden by File menu

@item Shift-Alt-f
Select the next word (forward).

@item Ctrl-a
Go to the beginning of the line

@item Ctrl-e
Go to the end of the line

@item Ctrl-d
Delete the next character

@c @item Alt-d  overridden by Debug menu
@c Delete to the end of the word

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

@item Alt-\
Delete all space characters around the cursor.

@item Alt-space
Replace all space characters around the cursor by a single space.

@item Alt-<
Go to the beginning of the file

@item Alt->
Go to the end of the file

@c @item Ctrl-p overridden by find previous

@item Shift-Ctrl-p
Select from cursor to one line up.

@c @item Ctrl-n  overridden by find next

@item Shift-Ctrl-n
Select from cursor to one line down.

@item Ctrl-j
Join the current and the next lines and leave a single space between the
two. This is similar to the @key{J} key in the @i{vi} editor.
This is a useful extension compared to the default Emacs key bindings.
@end table

@end table

@c --------------------------------------------------------------------------
@node The File Selector
@section The File Selector
@cindex file selector
@c --------------------------------------------------------------------------

@cindex Windows
@noindent
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:

@iftex
@cindex screen shot
@image{open-file, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{open-file}
@end ifhtml

@noindent
This dialog provides the following areas and capabilities:

@itemize @bullet
@item A tool bar on the top composed of five buttons giving access to common
navigation features:

  @table @b
  @item left arrow
  go back in the list of directories visited

  @item right arrow
  go forward

  @item up arrow
  go to parent directory

  @item refresh
  refresh the contents of the directory

  @item home
  go to home directory (value of the HOME environment variable, or @code{/} if
  not defined)
  @end table

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

@item A directory tree. You can open or close directories by clicking on the
@code{+} and @code{-} icons on the left of the directories, or
navigate using the keyboard keys: @key{up} and @key{down} to select the
previous or the next directory, @key{+} and @key{-} to expand and collapse
the current directory, and @key{backspace} to select the parent directory.

@item 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@dots{}

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

@item 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 @key{Tab} key.

@item A button bar with the @code{OK} and @code{Cancel} buttons.
When you have selected the right file, clock on @code{OK} to confirm, or
click on @code{Cancel} at any time to cancel and close the file selection.

@end itemize

@c --------------------------------------------------------------------------
@node Menu Items
@section Menu Items
@cindex menu
@c --------------------------------------------------------------------------

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

@subsection The File Menu
@anchor{The File Menu}
@noindent

@table @b
@item New
@cindex new file
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.

@cindex Ada
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.

@item New View
@cindex new view
@cindex 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.

@item Open...
@cindex open
@cindex Windows
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 @ref{The File Selector}.

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

@iftex
@cindex screen shot
@image{open-from-project, 7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{open-from-project}
@end ifhtml

The first text area allows you to type a file name. You can start the beginning
of a file name, and use the @key{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.

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

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

Once you have made your choice, click on the @code{OK} button to validate.
Clicking on @code{Cancel} or hitting the @key{Esc} key will cancel the
operation and close the dialog.

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

@item Save
@cindex save
Save the current source editor if needed.

@item Save As...
@cindex save as
Same current file under a different name, using the file selector dialog.
@xref{The File Selector}.

@item Save...
@cindex save
Give access to extra save capabilities.

@table @i
@c @item All Editors
@c Save all modified source editors.

@item All
@cindex save all
Save all items, including projects, etc@dots{}

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

@item Default Desktop
@cindex save 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.

@end table

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

@item Messages
@cindex messages
This sub menu gives access to functionalities related to the Messages window.
@xref{The Messages Window}.

@table @i
@item Clear
@cindex messages
@cindex clear
Clear the contents of the Messages window.

@item Save As...
@cindex 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.

@item Load Contents...
@cindex load
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.
@xref{The Locations Tree}.

@end table

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

@c @item Close All
@c Close all windows.

@item Print
@cindex print
Print the current file by first saving it interactively if needed (if it has
been modified), and then by launching the command defined in the preferences.
@xref{Print Command}.

@item Exit
@cindex exit
@cindex quit
Exit GPS after confirmation and if needed, confirmation about saving modified
windows and editors.

@end table

@subsection The Edit Menu
@anchor{The Edit Menu}
@cindex menu
@cindex edit
@noindent

@table @b
@item Undo
@cindex undo
Undo previous insertion/deletion in the current editor.

@item Redo
@cindex redo
Redo previous insertion/deletion in the current editor.

@item Cut
@cindex cut
Cut the current selection and store it in the clipboard.

@item Copy
@cindex copy
@cindex yank
Copy the current selection to the clipboard.

@item Paste
@cindex paste
Paste the contents of the clipboard to the current cursor position.

@item Select All
@cindex select all
Select the whole contents of the current source editor.

@item Comment Lines
@cindex comment
Comment the current selection or line based on the current programming
language syntax.

@item Uncomment Lines
@cindex uncomment
Remove the comment delimiters from the current selection or line.

@item Generate Body
@cindex gnatstub
@cindex generate body
Generate Ada body stub for the current source editor by calling the
external tool @code{gnatstub}.

@item Pretty Print
@cindex gnatpp
@cindex pretty print
Pretty print the current source editor by calling the external tool
@code{gnatpp}. It is possible to specify @code{gnatpp} switches in the
switch editor. @xref{The Switches Editor}.

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

@table @i
@item New Test Case...
Create a new test case. See AUnit documentation for more details.

@c @item Add Routine...
@c Add a new routine in the current test. See AUnit documentation for more details.

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

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

@end table

@item Preferences
@cindex preferences
Give access to the preferences dialog. @xref{The Preferences Dialog}.
@end table

@c --------------------------------------------------------------------------

@c --------------------------------------------------------------------------
@node Using an External Editor
@section Using an External Editor
@cindex editor
@cindex external editor
@cindex emacs
@cindex vi
@c --------------------------------------------------------------------------

@noindent
GPS is fully integrated with a number of external editors, in
particular @code{Emacs} and @code{vi}. The choice of the default
external editor is done in the preferences. @xref{The Preferences Dialog}.
@cindex preferences
The following values are recognized:

@table @code
@item gnuclient
@cindex 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
@file{.emacs} file (create one if needed) so that the same Emacs frame
is reused every time:

@cindex example
@smallexample
   (setq gnuserv-frame (car (frame-list)))
@end smallexample

@cindex url
See @url{http://www.hpl.hp.co.uk/people/ange/gnuserv/} for more information.

@item emacsclient
@cindex 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.


@item emacs
@cindex emacs
This client will start a new Emacs session every time a file needs to
be opened. You should use @code{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 @code{emacsclient}.


@item vim
@cindex vim
@code{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.

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


@item vi
@cindex vi
This editor works exactly like vim, but uses the standard @code{vi}
command instead of @code{vim}.


@item custom
@cindex custom editor
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 @ref{custom editor command}).

@item none
No external editor is used, and the contextual menus simply won't
appear.
@end table


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.

@cindex menu
Alternatively, you can reload explicitly the project from
Emacs itself by using the menu @code{Project->Load}


@cindex preferences
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.

@c --------------------------------------------------------------------------
@node Using the Clipboard
@section Using the Clipboard
@cindex clipboard
@cindex cut
@cindex copy
@cindex yank
@cindex paste
@cindex X-Window
@c --------------------------------------------------------------------------

@noindent
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 @i{GPS clipboard} is set by explicit
cut/copy/paste actions, either through menu items or keyboard
shortcuts, and the @i{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
@i{primary clipboard} will still work, provided that there is some
text currently selected. The @i{GPS clipboard}, when set, will
override the @i{primary clipboard}.

@cindex url
See @url{http://www.freedesktop.org/standards/clipboards.txt} for more
information.

@c --------------------------------------------------------------------
@node Source Navigation
@chapter Source Navigation
@cindex source navigation
@cindex navigation
@c --------------------------------------------------------------------

@menu
* Support for Cross References::
* The Navigate Menu::
* Source Navigation Contextual Menus::
@end menu

@c --------------------------------------------------------------------
@node Support for Cross References
@section Support for Cross References
@cindex cross references
@c --------------------------------------------------------------------

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

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

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

@cindex ALI
There are a few special cases where GPS can not find the external file
(called @file{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
@file{ALI file} was generated.

@cindex project
It could also be that you haven't included in the project the object
directories that contain the @file{ALI files}.

@cindex separate unit
In addition, one special case can not be handled automatically. This
is for separate units, whose file names have been crunched through the
@command{gnatkr} command. To handle this, you should force GPS to parse
all the @file{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".

@item C/C++
@cindex C
@cindex 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.

@cindex overloaded
@cindex #ifdef
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
@code{#ifdef} sections, are defined. In this case, GPS will display a
dialog listing the possible choices to resolve the ambiguity.

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

@end table

@c --------------------------------------------------------------------
@node The Navigate Menu
@section The Navigate Menu
@cindex navigate
@c --------------------------------------------------------------------

@noindent

@table @b
@item Find/Replace...
@cindex find
@cindex search
@cindex replace
Open the find and replace dialog. @xref{Searching and Replacing}.

@item Find Next
@cindex find next
Find next occurrence of the current search. @xref{Searching and Replacing}.

@item Find Previous
@cindex find previous
Find previous occurrence of the current search.
@xref{Searching and Replacing}.

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

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

@item Goto Line...
@cindex 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.

@item Goto File Spec<->Body
@cindex goto file spec/body
@cindex Ada
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

@c @item Goto Parent Unit
@c @cindex goto parent unit
@c This item is also accessible through the editor's contextual menu

@item Find All References
@anchor{Find All References}
@cindex 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 @ref{The Locations Tree}.

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

@c @item Start Of Statement
@c @item End Of Statement
@c @item Next Procedure
@c @item Previous Procedure

@item Previous Tag
@cindex tag
@cindex previous tag
@cindex locations tree
Go to previous tag/location. @xref{The Locations Tree}.

@item Next Tag
@cindex tag
@cindex next tag
@cindex locations tree
Go to next tag/location. @xref{The Locations Tree}.

@end table

@c --------------------------------------------------------------------
@node Source Navigation Contextual Menus
@section Source Navigation Contextual Menus
@cindex contextual menu
@c --------------------------------------------------------------------

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

@table @b
@item Goto declaration of @i{entity}
@cindex goto declaration
Go to the declaration/spec of @i{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.

@item Goto body of @i{entity}
@cindex goto body
Go to the body/implementation of @i{entity}.
This capability requires support for cross references.

@item Goto file spec/body
@cindex goto file spec/body
@cindex Ada
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.

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

@table @command
@item @i{Entity} calls
@cindex call graph
@cindex calls
Open or raise the call graph browser on the specified entity and display all
the functions called by @i{entity}. @xref{Call Graph}.

@item @i{Entity} is called by
@cindex call graph
@cindex called by
Open or raise the call graph browser on the specified entity and display all
the functions calling @i{entity}. @xref{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.

@item Find all references to @i{entity}
@cindex find all references
@xref{Find All References}.

@item Find all local references to @i{entity}
@cindex find all local references
Find all references to @i{entity} in the current file (or in the current
top level unit for Ada sources).
See @ref{Find All References} for more details.

@item Find all writes to @i{entity}
@cindex find all writes
Find all writes to an entity. This is a search global to the project.
See @ref{Find All References} for more details.

@item Find all reads of @i{entity}
@cindex find all reads
Find all non write accesses to an entity. This is a search global to the
project.
See @ref{Find All References} for more details.

@end table

@end table

@c --------------------------------------------------------------------
@node Project Handling
@chapter Project Handling
@cindex project
@c --------------------------------------------------------------------

@noindent
@cindex project explorer
The section on the project explorer (@ref{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.

@menu
* Description of the Projects::
* Scenarios and Configuration Variables::
* The Project Explorer (Editing Projects)::
* The Project Menu::
* The Project Wizard::
* The Project Properties Editor::
* The Switches Editor::
* The Project Browser::
@end menu

@c -------------------------------------------------------------------
@node Description of the Projects
@section Description of the Projects
@cindex project description
@c -------------------------------------------------------------------

@subsection Project files and GNAT tools
@cindex project file
@cindex GNAT

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

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

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

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

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

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

@cindex Ada
@cindex gpr2make
If you are using programming languages other than Ada, the project
files can automatically generate Makefiles through the @file{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.

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

@itemize @bullet
@item absolute paths
@item 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.
@item 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.
@end itemize


@subsection Contents of project files
@cindex project file

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

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

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

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

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

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

@item @b{List of source directories}:
@cindex source directory
   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.

@item @b{Object directory}:
@cindex 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.

@item @b{Exec directory}:
@cindex 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.

@item @b{List of source files}:
@cindex source file
   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.

@item @b{List of main units}:
@cindex main unit
   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.

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

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

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

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

@item @b{Tools}:
@cindex tools
   The project files provide a simple way to change the compiler that
   should be used to compile the source files, as well as the
   underlying debugger to use.

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

@end itemize


@c -------------------------------------------------------------------
@node Scenarios and Configuration Variables
@section Scenarios and Configuration Variables
@cindex configuration variable
@cindex project variable
@cindex variable
@c -------------------------------------------------------------------

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

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

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


@subsection Creating new configuration variables
@cindex creating configuration variable

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

@iftex
@cindex screen shot
@image{scenarios, 10cm}
@end iftex

@ifhtml
@cindex screen shot
@image{scenarios}
@end ifhtml

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:

@itemize @bullet
@item It is displayed in the project explorer
@cindex project explorer

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

@end itemize

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 @code{Remove},
@code{Add} and @code{Rename} buttons, although you can also simply
click on the value itself to change it.


@subsection Editing existing configuration variables
@cindex editing configuration variable

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

@iftex
@cindex screen shot
@image{explorer-scenario, 8.5cm}
@end iftex

@ifhtml
@cindex screen shot
@image{explorer-scenario}
@end ifhtml

@cindex Unix
This screen shot shows two configuration variables, named @code{Build}
and @code{OS}, with their current value (resp. @code{Debug} and
@code{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.

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

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

@c ??? Need to explain how to force an update, once this is implemented

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

@cindex removing variable
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.

@c -------------------------------------------------------------------
@node The Project Explorer (Editing Projects)
@section The Project Explorer
@cindex project explorer
@c -------------------------------------------------------------------

@noindent
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.

@cindex limited with
Likewise, if you have edited the project manually and have used the
@code{limited with} construct to have cycles in the project
dependencies, the cycle will expand infinitely. For instance, if
project @file{a} imports project @file{b}, which in turns imports
project @file{a} through a @code{limited with} clause, then expanding
the node for @file{a} will show @file{b}. In turn, expanding the node
for @file{b} will show a node for @file{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, @dots{})

The following entries are available in the contextual menu:

@table @command
@item 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.

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

@item 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, @dots{} @xref{The Project Properties Editor}.

@item Add Dependency...
@cindex 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.

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

@item Add Configuration Variable
@cindex add configuration variable
This menu item should be used to add new configuration variables, as
described in @ref{Scenarios and Configuration Variables}.

@item Edit Project Source File
@cindex 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, @dots{})

@end table

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

@iftex
@cindex screen shot
@image{project-modified}
@end iftex

@ifhtml 
@cindex screen shot
@image{project-modified}
@end ifhtml

@c -------------------------------------------------------------------
@node The Project Menu
@section The Project Menu
@cindex project menu
@c -------------------------------------------------------------------

The menu bar item @code{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, @dots{}).
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:

@table @command
@item New
This menu will open the project wizard (@ref{The Project Wizard}), so
that you can create new projects. On exit, the wizard asks whether the
newly project should be loaded. If you select @code{Yes}, the newly
project will replace the currently loaded project hierarchy.

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

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

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

@item Save All
This will save all the modified projects in the hierarchy.

@item 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, @xref{The
Switches Editor}.

@item Recompute Project
@cindex recompute project
@cindex C
@cindex C++
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.

@item 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.

@end table

@c -------------------------------------------------------------------
@node The Project Wizard
@section The Project Wizard
@cindex project wizard
@c -------------------------------------------------------------------

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

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

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

@iftex
@cindex screen shot
@image{project-wizard, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{project-wizard}
@end ifhtml

The wizard gives access to the following list of pages:

@itemize @bullet
@item Project Naming
@item VCS Selection
@item Source Directories Selection
@item Build Directory
@item Naming Scheme
@item Main Units
@item Switches
@end itemize

@c ------------------------------------------------------------------
@subsection Project Naming
@c ------------------------------------------------------------------

@noindent
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 @code{Forward} button.

In this page, you should also select what languages the source files
in this project are written in. Currently supported are @code{Ada},
@code{C} and @code{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).

@c ------------------------------------------------------------------
@subsection VCS Selection
@cindex Version Control System
@cindex VCS
@c ------------------------------------------------------------------

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

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

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

If left blank, no program will be run.

@c ------------------------------------------------------------------
@subsection Source Directories Selection
@c ------------------------------------------------------------------

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

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

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

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

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

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

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

@c ------------------------------------------------------------------
@subsection Build Directory
@cindex object directory
@cindex exec directory
@c ------------------------------------------------------------------

@noindent
The object directory is the location where the files resulting from
the compilation of sources (@file{.o} files for instance) are put.

One object directory is associated for each project.

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

@c ------------------------------------------------------------------
@subsection Naming Scheme
@cindex naming scheme
@c ------------------------------------------------------------------

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

GPS is very flexible in that respect, and allows you to specify the
default extension for the files in this language. GPS makes a
distinction between spec (or header) files, which generally contains
no executable code, only declarations, and body files which contain
the actual code. For languages other than Ada, this header file is
used rather than the body file when you select @code{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 (@file{.ads}
for specs and @file{.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.

@iftex
@cindex screen shot
@image{naming-scheme, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{naming-scheme}
@end ifhtml

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

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

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

@c ------------------------------------------------------------------
@subsection Main Units
@cindex main units
@c ------------------------------------------------------------------

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

Typically, for C applications, these are the files that contain the
@code{main()} function. For Ada applications, these are the files that
contain the main subprogram for the partition.

These files are treated specially by GPS. Some sub-menus of
@code{Build} and @code{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 @code{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.

@c ------------------------------------------------------------------
@subsection Switches
@anchor{Switches}
@cindex switches
@c ------------------------------------------------------------------

@noindent
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, @dots{}).

@iftex
@cindex screen shot
@image{switch-editor, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{switch-editor}
@end ifhtml

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

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

@item 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.
@end table

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.

@c -------------------------------------------------------------------
@node The Project Properties Editor
@section The Project Properties Editor
@cindex project properties editor
@c -------------------------------------------------------------------

@noindent
The project properties editor gives you access at any time to the properties
of your projects. It is accessible through the menu
@code{Project->Edit Project Properties}, and through the contextual menu
@code{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, @dots{}), a warning dialog is displayed when you
select the menu. This reminds you that the project might be only
partially loaded, and editing it might result in the loss of data. In
such cases, it is recommended that you edit the project file manually,
which is doable directly from the pop-up dialog.

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

@iftex
@cindex screen shot
@image{project-properties, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{project-properties}
@end ifhtml

This editor is divided into three parts:

@table @b
@item The attributes editor
The contents of this editor is very similar to that of the project
wizard (@pxref{The Project Wizard}). In fact, all pages but the
@code{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, @dots{}).

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

Clicking on the right title bar (@code{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.

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

Clicking on the left title bar (untitled, on the left of the @code{Scenario}
label) will select all values of all variables.

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

@end table

@c -------------------------------------------------------------------
@node The Switches Editor
@section The Switches Editor
@cindex switches editor
@c -------------------------------------------------------------------

@noindent
The switches editor, available through the menu @code{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 (@pxref{The Project Properties Editor}). They are defined
in black if they are specific to a given file.

Double-clicking in the switches column allows you to edit the switches
for a specific file. It is possible to edit the switches for multiple
files at the same by selecting them before displaying the contextual
menu (@code{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 @code{Revert}. Clicking on this button
will cancel any file-specific switch, and revert to the default
switches defined at the project level.

@iftex
@cindex screen shot
@image{switch-editor-revert, 11.7cm} 
@end iftex

@ifhtml 
@cindex screen shot
@image{switch-editor-revert}
@end ifhtml

@c -------------------------------------------------------------------
@node The Project Browser
@section The Project Browser
@cindex project browser
@c -------------------------------------------------------------------

@noindent
The project graph is a special kind of browser (@pxref{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.

@cindex examine projects imported by
It is accessed through the contextual menu in the project explorer, by
selecting the @code{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@dots{}
@xref{The Project Explorer (Editing Projects)}.

@iftex
@cindex screen shot
@image{project-browser, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{project-browser}
@end ifhtml

Some new items are added to the menu:

@table @command
@item Locate in explorer
@cindex 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.

@item Show dependencies
@cindex 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

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

@item Show projects depending on
@cindex show projects depending on
This item plays the same role as the left arrow in the title bar, and
display all the projects that import directly the selected project.
@end table

@c --------------------------------------------------------------------
@node Searching and Replacing
@chapter Searching and Replacing
@cindex find
@cindex search
@cindex replace
@c --------------------------------------------------------------------

@noindent
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,@dots{}
@cindex project explorer

@cindex menu
@cindex key
@cindex search context
All these search contexts are grouped into a single graphical window,
that you can open either through the menu @code{Navigate->Find/Replace...}, or
the shortcut @key{Ctrl-F}.

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

@iftex
@cindex screen shot
@image{search-hide, 7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{search-hide}
@end ifhtml

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

@table @command
@item Search for
@cindex 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 @code{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,@dots{}
@cindex C++
@cindex Ada

@item Replace with
@cindex 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.

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

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

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

@cindex search context
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.

@end table

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.

@iftex
@cindex screen shot
@image{search-options, 7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{search-options}
@end ifhtml

There are four check boxes in this options box.

@table @b
@item @code{"Search All Occurrences"}
@cindex 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 @code{Next} button (or the equivalent shortcut
@key{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 @code{Locations} (initially found in the bottom dock of
the GPS window). You can interrupt the search at any time by pressing
the @code{Stop} button: this will stop when the next occurrence is found.

@item @code{"Case Sensitive"}
@cindex 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.

@item @code{"Whole Word Only"}
@cindex whole word
If activated, this check box will force the search engine to ignore
substrings. "sensitive" will no longer match "insensitive".

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

@end table

@cindex MDI
@cindex Multiple Document Interface
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.

@cindex menu
To force this behavior, open the menu @code{Window}, select
@code{Search} in the list at the bottom of the menu, and then select
either @code{Floating} or @code{Docked}.

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


@c --------------------------------------------------------------------
@node Compilation/Build
@chapter Compilation/Build
@cindex compilation
@cindex build
@c --------------------------------------------------------------------

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

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

@menu
* The Build Menu::
@c * Multi-language Build::
* Integrating existing build procedures with the GPS build system::
@end menu

@node The Build Menu
@section The Build Menu
@noindent
The build menu gives access to capabilities related to checking, parsing and
compiling files, as well as creating and running executables.

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

@item Compile File
Compile the current file. Display an error message in the @i{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
@ref{The Preferences Dialog}).
To remove the highlighting on these lines, remove the files from the Locations
Tree.

This option is currently only supported for Ada files.

@item Make
   @table @i
   @item 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 @code{Build} contextual menu accessible from a project
   entity contains the same entries.

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

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

   @item 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,
   @dots{} and want to invoke them from GPS.

   @end table

@item Recompute C/C++ Xref info
@cindex C
@cindex C++
Recompute the cross reference information for C and C++ source files.
@xref{Support for Cross References}.

@item Run
   @table @i
   @item 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 (@i{Helpers->Execute command}).

   Similarly, the @code{Run} contextual menu accessible from a project
   entity contains the same entries.

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

@item Interrupt
Interrupt the current compilation or build.

@end table

@c @node Multi-language Build
@c @section Multi-language Build
@c @noindent

@c ??? missing doc for multi language builds: explain how the generated
@c make files work, ...

@node Integrating existing build procedures with the GPS build system
@section Integrating existing build procedures with the GPS build system
@noindent
@i{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 @i{foreign project}.

You first need to provide your own @code{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:
@cindex Unix

@cindex example
@smallexample
$ chmod -w Makefile.<project>
@end smallexample

@cindex Windows
or under Windows:

@smallexample
@cindex example
> attrib +r Makefile.<project>
@end smallexample

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:

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

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

@item SRC_DIRS
Blank separated list of source directories.

@item LDFLAGS
Linker options.

@item LIBS
Additional libraries that this foreign project uses.

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

@end table

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

@cindex example
@smallexample
ifeq ($(FOO_PROJECT),)
FOO_PROJECT=True

ifeq ($(BASE_DIR),)
   BASE_DIR=$(shell pwd)
   FOO_ROOT=True

# Redirect clean to the real clean rule
   internal-clean:
        $(MAKE) clean

# Ditto for the build rule
   internal-build:
        $(MAKE) build
endif

FOO_BASE_DIR := $(BASE_DIR)

# Add our source directories to the default search path
# so that other projects can reference our include files
FOO_SRC_DIRS = $(FOO_BASE_DIR)/include $(FOO_BASE_DIR)/include2
SRC_DIRS += $(FOO_SRC_DIRS)

# Add <build>/libfoo.a, built by the internal-build rule above, to the
# list of libraries to link with
LIBS := $(FOO_BASE_DIR)/<build>/libfoo.a $(LIBS)

ifneq ($(FOO_ROOT),True)
   DEPS_PROJECTS += $(FOO_BASE_DIR)/foo
endif

endif
@end smallexample

@c --------------------------------------------------------------------
@node Source Browsing
@chapter Source Browsing
@cindex source browsing
@c --------------------------------------------------------------------

@menu
* General Issues::
* Call Graph::
* Dependency Browser::
* Entity Browser::
@end menu

@c --------------------------------------------------------------------
@node General Issues
@section General Issues
@c --------------------------------------------------------------------

@noindent
GPS contains several kinds of browsers, that have a common set of
basic functionalities. There are currently four such browsers: the
project browser (@pxref{The Project Browser}), the call graph
(@pxref{Call Graph}), the dependency browser (@pxref{Dependency
Browser}) and the entity browser (@pxref{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, @dots{}).

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

@table @b
@item 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.

@item 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 @code{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.

@item 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.

@item 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 @code{orthogonal links} in the
background contextual menu.

@item Zooming
Several different zoom levels are available. The contextual menu in
the background of the browser contains three entries: @code{zoom in},
@code{zoom out} and @code{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.

@item Selecting items
Items can be selected by clicking inside them. Multiple items can be
selected by holding the @key{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.

@item 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. 

@end table

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, @dots{}). 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:

@table @command
@item 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.

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

@end table

@c --------------------------------------------------------------------
@node Call Graph
@section Call Graph
@cindex call graph
@c --------------------------------------------------------------------

@noindent
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.

@cindex renaming entities
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.

@iftex
@cindex screen shot
@image{call-graph, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{call-graph}
@end ifhtml

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:

@table @command
@item References->@i{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.

@item References->@i{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.
@end table

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.

@table @command
@item @i{Entity} calls
Same as described above.

@item @i{Entity} is called by
Same as described above.

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

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

@item 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.
@end table

@c --------------------------------------------------------------------
@node Dependency Browser
@section Dependency Browser
@cindex dependency browser
@c --------------------------------------------------------------------

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

@iftex
@cindex screen shot
@image{dependency-browser, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{dependency-browser}
@end ifhtml

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 (@code{with}
statement in Ada, or @code{#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:

@table @command
@item Show dependencies for @i{file}
@cindex show dependencies for

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.

@item Show files depending on @i{file}
@cindex show files depending on

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.

@end table

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

@table @command
@item Open file...

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

@item Refresh
@cindex 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,...)

@item Show system files
@cindex 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 @code{Open file} menu, or the contextual menu in the
project explorer.

@item Show implicit dependencies
@cindex 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 @code{with} or @code{#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.

@end table

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

@table @command
@item Analyze other file
@cindex 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 @file{.h} file to a @file{.c} file and back.

@item Show dependencies for @i{file}
@cindex show files depending on file

These play the same role as in the project explorer contextual menu

@end table

@c --------------------------------------------------------------------
@node Entity Browser
@section Entity Browser
@cindex entity browser
@c --------------------------------------------------------------------

@noindent
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:

@table @code
@item 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.

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

@item Subprograms
The list of parameters is displayed

@item Packages
The list of all the entities declared in that package is displayed

@item and more ...

@end table

@iftex
@cindex screen shot
@image{entity-browser, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{entity-browser}
@end ifhtml

This browser is accessible through the contextual menu in the
explorer, when clicking on an entity:

@table @command
@item Examine entity @i{entity}
@cindex examine entity

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

@end table

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.

@c --------------------------------------------------------------------
@node Debugging
@chapter Debugging
@cindex debugger
@cindex debugging
@c --------------------------------------------------------------------

@noindent
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
@ifhtml
(@url{gdb.html})
@end ifhtml
- for more details.

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

@cindex menu
To start a debug session, go to the menu @code{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 @code{<no main file>} item. It is then possible to load
any file to debug, by using the menu @code{Debug->Debug->Load File...}

After the debugger has been initialized, you have access to two new windows:
the data window (in the top of the working area), and the debugger console
(in a new page, after the Messages and Shell windows).
All the menus under @code{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 @i{tool tips}) of object values.

@cindex menu
When you want to quit the debugger without quitting GPS, go to the menu
@code{Debug->Terminate}, which will terminate your debug session.

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

@include ../gvd/docs/gvd_contents.texi

@c --------------------------------------------------------------------
@node Version Control System
@chapter Version Control System
@cindex version control
@c --------------------------------------------------------------------

@menu
* The VCS Explorer::
* The VCS Menu::
* The Version Control Contextual Menu::
@end menu

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 @code{VCS} tab in the Project property
editor. @xref{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.

@node The VCS Explorer
@section The VCS Explorer
@cindex VCS explorer
@cindex version control
@noindent

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

@iftex
@cindex screen shot
@image{vcs-explorer, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{vcs-explorer}
@end ifhtml

The easiest way to bring up the VCS Explorer is through the menu
@code{VCS->Explorer}. The Explorer can also be brought up using the
contextual menu @code{Version Control->Query status} on files,
directories and projects in the file and project views, and on file
editors. @xref{The Version Control Contextual Menu}.

The VCS Explorer contains the following columns:

@table @b
@item 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:

@table @code
@item 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).

@item Not registered
The file is not known to the VCS repository.

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

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

@item Modified
The file has been modified by the user or has been explicitly opened
for editing.

@item Needs merge
The file has been modified locally and on the repository.

@item Needs update
The file has been modified in the repository but not locally.

@end table

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

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

@item Working rev.
Indicates the version of the local file.

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

@end table

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 @key{Shift} key and select the
last line in the range. To add or remove single columns from the
selection, hold down the @key{Control} key and left-click on the
columns that you want to select/unselect.

@cindex interactive search
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 @key{Ctrl-i}. See @ref{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. @xref{The Version
Control Contextual Menu}.

@node The VCS Menu
@section The VCS Menu
@cindex version control
@cindex menu
@noindent

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. @xref{The Version Control Contextual Menu}.

@table @b
@item Explorer
Open or raise the VCS Explorer. @xref{The VCS Explorer}.

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

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

@item Update
@anchor{Update}
Update the currently selected item (file, directory or project).

@item Commit
@anchor{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 @code{File checker} in the
@code{VCS} tab of the project properties dialog. This @code{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 @code{Log checker} in the project properties dialog. This
works on change-log files in the same way as the @code{File checker} works on
source files.

@item Start Editing
@anchor{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.

@item View revision history
@anchor{View revision history}
Show the revision logs for all previous revisions of this file.

@item Compare against head rev.
@cindex compare
@anchor{Compare against head}

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

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

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

@item Annotate
@anchor{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.

@item Remove annotations
Remove the annotations from the selected file.

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

@c @item Revert
@item Add to repository
Add a file to the repository.

@item Remove from repository
Remove a file from the repository.

@end table

@node The Version Control Contextual Menu
@section The Version Control Contextual Menu
@noindent
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.

@table @b
@item Query status
Query the status of the selected item. Brings up the VCS Explorer.

@item Update
Update the selected item. @xref{Update}.

@item Commit via revision log
This menu item is titled @i{Commit} when a revision log has already been
created.
@xref{Commit}.

@item Start editing
Open the selected file for editing. @xref{Start Editing}.

@item View revision history
View the revision history for the selected file. @xref{View revision history}.

@item Compare against head rev.
@cindex compare
Compare selected files. @xref{Compare against head}.

@item Compare against working rev.
Compare selected files. @xref{Compare against working}.

@item Compare working against head rev.
Compare selected files. @xref{Compare working against head}.

@item Annotate
@cindex annotate
Enable annotations for the selected files.
@xref{Annotate}.

@item Remove annotations
Remove annotations for the selected files.

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

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

@item Add to repository
Add the selected items to the repository.

@item Remove from repository
Remove the selected items from the repository.

@item Directory
Only available when the current context contains directory information

@table @i
@item Query status for directory
Query status for the files contained in the selected directory.

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

@item Update directory
Update the files in the selected directory.

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

@end table

@item Project
Only available when the current context contains project information

@table @i
@item List all files in project
Brings up the VCS Explorer with all the source files contained in the project.

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

@item Update project
Updates all the source files in the project.

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

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

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

@end table

@item Hide up-to-date files
@anchor{Hide up-to-date files}
@cindex filter
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.

@item Hide non registered files
@anchor{Hide non registered files}
@cindex filter
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).

@end table

@c --------------------------------------------------------------------
@node Tools
@chapter Tools
@cindex tools
@c --------------------------------------------------------------------

@menu
* The Tools Menu::
* Visual Comparison::
* Code Fixing::
@end menu

@node The Tools Menu
@section The Tools Menu
@noindent
The @code{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:

@table @b
@item Shell Console
@cindex shell

Open a shell console at the bottom are of GPS.
@xref{The Shell Window}.

@item Call Graph
@xref{Call Graph}.

@item Dependency Browser
@xref{Dependency Browser}.

@item Entity Browser
@xref{Entity Browser}.

@item Compare
@xref{Visual Comparison}.

@end table

@node Visual Comparison
@section Visual Comparison
@cindex visual diff
@noindent
@i{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, @dots{}}.

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 @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
(@url{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.

@iftex
@cindex screen shot
@image{visual-diff, 12.7cm} 
@end iftex

@ifhtml
@cindex screen shot
@image{visual-diff}
@end ifhtml

Colors are used to display the different kinds of chunks:

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

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

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

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

@end table

@node Code Fixing
@section Code Fixing
@cindex code fixing
@cindex wrench icon
@noindent

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

@c There are two ways to access this capability: the first (and preferred) one
@c is integrated with the @i{Locations tree} (see @ref{The Locations Tree}); the
@c other provides a separate dialog accessible through the menu
@c @code{Tools->Code Fixing}.

This capability is integrated with the @i{Locations tree} (see
@ref{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 @i{Code Fixing} gives you
access to the same information. In the previous example of a missing
semicolon, the menu will contain an entry labeled @i{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.

@c --------------------------------------------------------------------
@node Working in a Cross Environment
@chapter Working in a Cross Environment
@cindex cross environment
@c --------------------------------------------------------------------

@menu
* Customizing your Projects::
* Debugger Issues::
@end menu

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

@node Customizing your Projects
@section Customizing your Projects
@cindex project

@noindent
This section describes some possible ways to customize your projects when
working in a cross environment. For more details on the project capabilities,
see @ref{Project Handling}.

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

In the @code{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 @i{Ada compiler} to
@code{powerpc-wrs-vxworks-gnatmake}; @i{Gnatls} to
@code{powerpc-wrs-vxworks-gnatls} and @i{Debugger} to
@code{powerpc-wrs-vxworks-gdb}.

If you are using an alternative run time, e.g. a @i{soft float} run time,
you need to add the option @code{--RTS=soft-float} to the @i{Gnatls}
property, e.g: @code{powerpc-wrs-vxworks-gnatls --RTS=soft-float}, and
add this same option to the @i{Make} switches in the switch editor.
See @ref{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
@ref{Scenarios and Configuration Variables} for more information on these
variables.

For example, you may want to create a variable called @code{Target} to handle
the different kind of targets handled in your project:

@table @b
@item Target
   Native, Embedded
@item Target
   Native, PowerPC, M68K
@end table

Similarly, you may define a @code{Board} variable listing the different
boards used in your environment and change the @i{Program host} and @i{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 @code{TARGET}),
and specify a different naming scheme for this body file (in the project
properties, @code{Naming} tab), based on the value of @code{TARGET}.

@node Debugger Issues
@section Debugger Issues
@cindex debugger
@noindent
This section describes some debugger issues that are specific to cross
environments. You will find more information on debugging by reading
@ref{Debugging}.

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

For example, if you are using the @i{Tornado} environment, with a target
server called @code{target_ppc}, set the @code{Protocol} to @code{wtx} and
the @code{Program host} to @code{target_ppc}.

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

In order to load a new module on the target, you can select the menu
@code{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
@code{Debug->Debug->Add Symbols...} to load the symbol tables in the current
debugger.

@c --------------------------------------------------------------------
@node Customizing and Extending GPS
@chapter Customizing and Extending GPS
@cindex customization
@c --------------------------------------------------------------------

@menu
* The Preferences Dialog::
* Customizing the Menu and Tool Bar::
* Adding Support for New Languages::
* Defining Text Aliases::
* Defining New Styles and Key Bindings::
* Scripting GPS::
@end menu

@node The Preferences Dialog
@section The Preferences Dialog
@anchor{preferences dialog}
@cindex preferences
@noindent
This dialog, available through the menu @code{Edit->Preferences}, allows you to
modify the global preferences of GPS.
To enable the new preferences, you simply need to confirm by pressing
the @code{OK} button. To test your changes, you can use the @code{Apply}
button. Pressing the @code{Cancel} button will undo all your changes.

@iftex
@cindex screen shot
@image{preferences-general, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{preferences-general}
@end ifhtml

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 @i{General}, @i{Editor}, @i{Debugger},
@i{Helpers}, @i{Browsers}, @i{Visual Diff}, @i{Messages} and @i{Project}.
Each page corresponds to a section of preferences.

@itemize @bullet
@item @b{General}

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

@table @i
@item General

@table @b
@item Default font
@cindex font
The default font used in GPS

@item Key theme
@cindex key theme
@cindex emacs
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 @code{Emacs} and @code{Default}

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

@item Dynamic key bindings
@cindex key binding
@cindex dynamic key binding
@anchor{Dynamic key bindings}
Whether the menu key bindings can be changed interactively.
@xref{Redefining key bindings}.

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

@item Display welcome window
@cindex welcome dialog
Whether GPS should display the welcome window for the selection of the project
to use.

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

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

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

@item Aliases key
@cindex aliases
Key to press to expand an alias in a source editor or a text entry
anywhere in GPS.
@end table

@item Windows
@cindex MDI
@cindex Multiple Document Interface
This section specifies preferences that apply to the @i{Multiple Document
Interface} described in @ref{Multiple Document Interface}.

@table @b
@item Opaque
@cindex opaque
If True, items will be resized or moved opaquely when not maximized.

@item Destroy floats
@cindex float
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.

@item All floating
@cindex float
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.

@item Background color
@cindex color
Color to use for the background of the MDI.

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

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

@item Select Window
@cindex selection
The key shortcut used to switch between windows.

@end table

@end table

@item @b{Editor}
@cindex editor
@table @i
@item General

@table @b
@item Strip blanks
@cindex strip blanks
Whether the editor should remove trailing blanks when saving a file.

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

@item Display line numbers
@cindex display line numbers
Whether the line numbers should be displayed in file editors.

@item Tooltips
@cindex tooltip
Whether tool tips should be displayed automatically.

@item Highlight delimiters
@cindex highlight delimiter
Whether matching delimiters should be highlighting. The list of delimiters
include: @code{@{@}[]()}

@item Autosave delay
@cindex autosave delay
@anchor{autosave delay}
The period (in seconds) after which a source editor is automatically saved.
0 if none.

Each modified file is saved under a file called @code{.#filename}, which is
removed on the next explicit save operation.

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

@item External editor
@cindex external editor
The default external editor to use.

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

@smallexample
xterm -geometry 80x50 -exec vi +%l %f
@end smallexample

The following substitutions are provided:
@table @code
@item %l
line to display

@item %c
column to display

@item %f
full pathname of file to edit

@item %e
extended lisp command

@item %p
top level project file name

@item %%
percent sign ('%')
@end table

@item 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.

@end table

@item Fonts & Colors
@cindex font
@cindex color

@table @b
@item Keywords
Font and colors used to highlight keywords.

@item 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.

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

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

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

@item Line highlighting color
Color for highlighting lines.

@item Default font
The font used in the source editor.

@end table

@item Ada
@cindex Ada

@table @b
@item Auto indentation
@cindex 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.

@item Use tabulations
@cindex tabulation
Whether the editor should use tabulations when indenting.

@item Default indentation
@cindex indentation level
The number of spaces for the default Ada indentation.

@item Continuation lines
@cindex continuation line
The number of extra spaces for continuation lines.

@item Declaration lines
@cindex declaration line
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:

@cindex example
@smallexample
variable1,
    variable2,
    variable3 : Integer;
@end smallexample

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

@cindex example
@smallexample
case Value is
   when others =>
      null;
end case;
@end smallexample

If this preference is set to @code{False}, this would be indented as:

@cindex example
@smallexample
case Value is
when others =>
   null;
end case;
@end smallexample

@end table

@item C/C++
@cindex C
@cindex C++

@table @b
@item Auto indentation
@cindex 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.

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

@item Default indentation
@cindex indentation
The number of spaces for the default indentation.

@end table

@item Keys
@cindex key

@table @b
@item Auto-indentation
@cindex indentation
Key used for auto-indenting lines or block of lines.

@item Completion
@cindex completion
Key used for automatic completion of identifiers.

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

@end table

@end table

@item @b{Debugger}
@cindex debugger
@table @i
@item General

@table @b
@item Color highlighting
@cindex color
Color used for highlighting in the debugger console.

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

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

Note that in this mode under Windows, the @code{Debug->Interrupt} menu
will not interrupt the debugged program. Instead, you need to hit
@key{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.

@item Show lines with code
Specifies whether blue dots should be displayed in the source editor for lines
that contain code. If set to @i{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.

@end table

@item Assembly
@cindex assembly
@table @b
@item Current assembly line
Color used to highlight the assembly code for the current line.

@item Range size
@cindex 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.

@end table

@item Data
@cindex data
Lets you change the preferences of the @i{Data Window}, in particular
the fonts and colors used to display the data graphically.

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

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

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

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

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

@end table

@item Memory
@cindex memory view
@table @b
@item Default color
Color used by default in the memory view window.

@item Color highlighting
Color used for highlighted items.

@item Selection
Color used for selected items.

@end table

@end table

@item @b{Helpers}
@cindex helper
@table @i
@item List processes
Command used to list processes running on the machine.

@item Remote shell
@cindex remote shell
Program used to run a process on a remote machine. You can specify arguments,
e.g. @code{rsh -l user}

@item Remote copy
@cindex remote copy
Program used to copy a file from a remote machine. You can specify arguments,
e.g. @code{rcp -l user}

@item Execute command
@cindex execution
Program used to execute commands externally.

@item Print command
@cindex print
@cindex a2ps
@cindex PrintFile
@anchor{Print Command}
Program used to print files. By default @code{a2ps}, available under GNU/Linux
systems. This utility can be used on most Unix systems, and can be downloaded
from @url{http://www.inf.enst.fr/~demaille/a2ps}

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

@end table

@item @b{Browsers}
@cindex browsers
@table @i
@item General

@table @b
@item Selected item color
@cindex color
Color to use to draw the selected item.

@item Background color
@cindex color
Color used to draw the background of the browsers.

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

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

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

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

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

@item Vertical layout
@cindex vertical layout
Whether the layout of the graph should be vertical (@i{True}) or
horizontal (@i{False}).

@end table

@item File Dependencies

@table @b
@item Show system files
@cindex Ada
@cindex C
Whether the system files (Ada runtime or standard C include files) should be
visible in the browser.

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

@end table

@end table

@item @b{Visual diff}
@cindex visual diff
@cindex file comparison
@table @i
@item Context length
@cindex context length
The number of lines displayed before and after each chunk of differences.
Specifying -1 will display the whole file.

@item Diff command
@cindex diff
@cindex -u
@cindex -c
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 @code{-c} nor @code{-u} switch).
Arguments of interest may include (this will depend on the version of diff
used):

@table @b
@item -b
Ignore changes in amount of white space.

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

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

@item -w
Ignore white space when comparing lines.

@end table

@item Patch command
@cindex patch
Command used to apply a patch. Arguments can also be specified.
@end table

@item @b{Messages}
@cindex messages
@table @i
@item Color highlighting
@cindex color
Color used to highlight text in the messages window.

@item Color highlighting
@cindex errors
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. (@ref{Compilation/Build})

@item Show build progress
@cindex build
@cindex build progress
Whether the progress bar should show progress during builds.

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

@item File index
@cindex file index
Index of filename in the file pattern.

@item Line index
@cindex line index
Index of the line number in the file pattern.

@item Column index
@cindex column index
Index of the column number in the file pattern.

@end table

@item @b{Project}
@cindex project
@table @i
@item Relative paths
@cindex relative path
Whether paths should be absolute or relative when the projects are modified.

@end table

@end itemize

@node Customizing the Menu and Tool Bar
@section Customizing the Menu and Tool Bar
@cindex customization
@noindent
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.

@subsection Redefining key bindings
@cindex key
@cindex key binding
@anchor{Redefining key bindings}
@noindent
In order to define or redefine key bindings, you first need to enable
the @i{dynamic key binding} feature in the Preferences dialog.
@xref{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 @key{Backspace} key.
Your changes will be saved when GPS exits, in a file called
@file{$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.

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

@cindex Unix
@cindex Windows
Here is an example for such a file:

@cindex example
@smallexample

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

    <Submenu>
      <Title>other menu</Title>
      <Menu_Item>
        <Title> (etc..)
      </Menu_Item>

      <Submenu>
        (...)
      </Submenu>
    </Submenu>
  </Submenu>
</Custom>

@end smallexample

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

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
@file{.bat} or @file{.cmd} file, and call this file using @code{cmd /c}.
Thus, the @code{Action} tag would look like:

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

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

@cindex example
@smallexample
<Submenu>
  <Title>Edit</Title>
  <Menu_Item>
    <Title>List GPS commands</Title>
    <GPS_Action>help</GPS_Action>
  </Menu_Item>
  <Menu_Item>
    <Title>Edit main.c</Title>
    <GPS_Action>edit main.c</GPS_Action>
  </Menu_Item>
</Submenu>
@end smallexample

See below for more information on this @code{GPS_Action} tag.


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

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

@cindex example
@smallexample

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

@end smallexample

Use the @code{/} separator to identify the sub menu in a menu. For
example, this adds a sub menu named @code{Olga} containing an item named
@code{Item} to the @code{Edit} menu.

@cindex example
@smallexample

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

@end smallexample

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

The following tags are available in a @code{Submenu} section:

@table @code
@item Title
Found inside a @code{Submenu} or @code{Menu_Item}: set title of the submenu or
menu item.

@item Menu_Item
A menu item inside a submenu.

@item Action
External command associated with a menu item.

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

@c The value of this attribute could also be "python".

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

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

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.

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

@end table

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

@cindex example
@smallexample

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

@end smallexample

The following tags are available in a @code{Toolbar_Item} section:

@table @code
@item Title
Name of the custom button.

@item Pixmap
Pixmap file associated with the tool bar button.

@item Action
External command associated with a tool bar button.

@item GPS_Action
GPS specific command associated with a tool bar button.

@end table

@subsection Macro arguments
@cindex menu
@cindex argument
@cindex substitution
@noindent
When using an @code{Action} node in a menu or tool bar item,
you can use macro arguments to pass to your shell commands. Macro arguments
are special parameters that are transformed every time the command is executed.
The following macro arguments are provided:

@table @code
@item %f
Base name of the currently opened file.

@item %F
Absolute name of the currently opened file.

@item %p
The current project. This is the name of the project, not the project file.

@item %pp
The current project file pathname.

@item %PP
The root project pathname.

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

@table @code
@item P
the root project.

@item p
the selected project, or the root project if there is no project selected.

@item r
recurse through the projects: sub projects will be listed as well as their
sub projects, etc@dots{}

@item d
list the source directories.

@item s
list the source files.

@item f
output the list into a file and substitute the parameter with the
name of that file.
@end table

@end table

@cindex example
Examples:

@table @code
@item %Ps
Replaced by a list of source files in the root project.

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

@item %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.
@end table

@c --------------------------------------------------------------------------
@node Adding Support for New Languages
@section Adding Support for New Languages
@c --------------------------------------------------------------------------

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

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

The following tags are available in a @code{Language} section:

@table @code
@item Name
A short string describing the name of the language.

@item 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.

@item Body_Suffix
A string describing the suffix of body/implementation files for this language.

@item Keywords
A V7 style regular expression for recognizing and highlighting keywords.
Multiple @code{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 @file{g-regpat.ads} in the GNAT run time.

@item Context
Describes the context used to highlight the syntax of a file.

   @table @code
   @item Comment_Start
   A string defining the beginning of a multiple-line comment.

   @item Comment_End
   A string defining the end of a multiple-line comment.

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

   @item String_Delimiter
   A character defining the string delimiter.

   @item Quote_Character
   A character defining the quote character, used for e.g. canceling the
   meaning of a string delimiter (@code{\} in C).

   @item Constant_Character
   A character defining the beginning of a character literal.

   @item 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.

   @item Syntax_Highlighting
   A boolean indicating whether the syntax should be highlighted/colorized.

   @item Case_Sensitive
   A boolean indicating whether the language (and in particular the identifiers
   and keywords) is case sensitive.
   @end table

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

   @table @code
   @item 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.

   @item Pattern
   Regular expression used to detect a language category.
   As for the @code{Keywords} node, multiple @code{Pattern} tags can be
   specified and will be concatenated into a single regular expression.

   @item Index
   Index in the pattern used to extract the name of the entity contained in
   this category.
   @end table

@ifset extendedlanguage
@item Project_Field
This tag describes the tools that are used to support this
language. The name of these tools is stored in the project files, and
therefore only a limited number of tools can be specified. Note that this
tag is currently only used by the project properties and wizard, and is
not taken into account by other components.

This nodes has two attributes:

   @table @code
   @item Name
   Name of the attribute in the project file. Currently, only
   @code{"compiler_command"} can be specified.

   @item Index
   If present, this attributes indicates the index to use for the
   attribute in the project file. The line defining this attribute
   would therefore look like:

   @smallexample
      for Name ("Index") use "value";
   @end smallexample

   The value of the index should be either the empty string or the
   name of the language.

   @end table

The value of this tag is the string to use in the project properties
editor when editing this project field.
@end ifset

@end table

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

@cindex example
@smallexample
<?xml version="1.0"?>
<Custom>
  <Language>
    <Name>Project File</Name>
    <Spec_Suffix>.gpr</Spec_Suffix>

    <Keywords>^(case|e(nd|xte(nds|rnal))|for|is|</Keywords>
    <Keywords>limited|null|others|</Keywords>
    <Keywords>p(ackage|roject)|renames|type|use|w(hen|ith))\b</Keywords>

    <Context>
      <New_Line_Comment_Start>--</New_Line_Comment_Start>
      <String_Delimiter>"</String_Delimiter>
      <Constant_Character>'</Constant_Character>
      <Can_Indent>True</Can_Indent>
      <Syntax_Highlighting>True</Syntax_Highlighting>
      <Case_Sensitive>False</Case_Sensitive>
    </Context>

    <Categories>
      <Category>
        <Name>package</Name>
        <Pattern>^[ \t]*package[ \t]+((\w|\.)+)</Pattern>
        <Index>1</Index>
      </Category>
      <Category>
        <Name>type</Name>
        <Pattern>^[ \t]*type[ \t]+(\w+)</Pattern>
        <Index>1</Index>
      </Category>
    </Categories>
  </Language>
</Custom>
@end smallexample


@c --------------------------------------------------------------------------
@node Defining Text Aliases
@section Defining Text Aliases
@cindex aliases
@c --------------------------------------------------------------------------

@noindent
GPS provides a mechanism known as @b{aliases}. These are defined
through the menu @code{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 @key{control-o}, controlled by a
preference), this name is removed from the source editor, and replaced
by the text you have associated with it.

@iftex
@cindex screen shot
@image{aliases, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{aliases}
@end ifhtml

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

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

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

The following special entities are currently defined:

@table @code
@item %_
This is the position where the cursor should be put once the
replacement text has been inserted in the editor.

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

@item %D
This is the current date, in ISO format. The year is displayed first,
then the month and the day

@item %H
This is the current time (hour, minutes and seconds)

@item %l
If the expansion of the alias is done in a source editor, this is the
line on which the cursor is when pressing @key{control-o}.

@item %c
This is similar to @i{%l}, except it returns the current column.

@item %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)

@item %d
If the expansion is done in a source editor, this is the directory in
which the current file is

@item %p
If the expansion is done in a source editor, this is the base name of
the project file to which the file belongs.

@item %P
If the expansion is done in a source editor, this is the full path
name to the project file (directory and base name).

@end table

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
@i{%(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:

@table @b
@item name
This is the name you use in the expansion text of the alias in the
@i{%(name)} special entity.

@item Environment
This specifies whether the default value of the parameter comes from
the list of environment variables set before GPS was started.

@item 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.

@end table

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 @i{%(name)}
entities in the expansion text.


@subsection Aliases files

@noindent
GPS manages multiple aliases files. One of them is editable
interactively by the user through the @code{Edit->Aliases} menu,
whereas all the others are defined system-wide, and are not editable
interactively.

The user-defined file is @file{$HOME/.gps/aliases}.

The system files are all the files stored in the directory
@file{<prefix>/share/gps/aliases}, where @file{<prefix>} is the path
in which GPS was installed. The aliases defined in these files are
read-only, and indicated as such in the aliases editor.

All the files have the same XML format, which can be seen in the
following example. Each alias has its own @i{<alias>} tag.

@smallexample
<?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>
@end smallexample

The following tags are available:

@table @code
@item alias
This indicates the start of a new alias. It has one mandatory
attribute, @code{name}, which the text to type in the source editor
before pressing @key{control-o}.

@item param
These are children of the @code{alias} node. There is one per
parameter of the alias. They have one mandatory attribute,
@code{name}, which is the name to type between @i{%(name)} in the
alias expansion text.

They have one optional attribute, @code{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.

@item text
This is a child of the @code{alias} node, whose value is the
replacement text for the alias.
@end table


@c --------------------------------------------------------------------------
@node Defining New Styles and Key Bindings
@section Defining New Styles and Key Bindings
@c --------------------------------------------------------------------------

@cindex Gtk+
@cindex gtkrc
@cindex resource file
@cindex Unix
@noindent
In addition to the preferences dialog, GPS can be configured through the
Gtk+ mechanism of @file{RC files}. You can create a text file called
@file{gtkrc} in the gps home directory (@file{~/.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, @dots{}

For example, you can set @key{Ctrl-v} in the source editors to scroll forward
one page. The following code defines this new key binding:

@cindex example
@smallexample

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

@end smallexample

@subsection Toplevel declarations
@noindent
An RC file is a text file which is composed of a sequence of declarations.
All the literals are case sensitive;
@code{#} characters delimit comments and the portion of a line after a
@code{#} 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.

@smallexample
toplevel-declarations ::=
   @{ declaration @}

declaration ::=
   include-file | pixmap-path | style-definition | binding-definition |
   enable-resource

include-file ::=
   @b{include} string_literal

pixmap-path ::=
   @b{pixmap_path} string_literal

style-definition ::=
   @b{style} resource-name [ = parent ]
   @{
      sequence-of-style
   @}

binding-definition ::=
   @b{binding} resource-name
   @{
      sequence-of-binding
   @}

enable-resource ::=
   @b{class} "widget-name" (@b{binding} | @b{style}) resource-name

resource-name ::=
   string_literal

@end smallexample

@noindent
The table below describes the meaning of each of these toplevel declarations:

@table @command
@item include @i{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.

@item pixmap_path @i{path}
Sets a path (a list of directories separated by colons) that will be searched
for pixmaps referenced in RC files.

@item style @i{name} [ = @i{parent} ] @{ ... @}
Declares a style. If @i{parent} is specified, @i{name} inherits its
default attributes from @i{parent}. You can specify @i{"default"} to designate
the default style, e.g:

@smallexample
style "my-style" = "default" @{ ... @}
@end smallexample

See @ref{Defining new styles} for more details.

@item binding name @{ ... @}
Declares a binding set.
See @ref{Defining new key bindings} for more details.

@item class @i{widget-name} (binding | style) @i{name}
Specifies a binding or style set for a particular set of visual objects.

@item resource-name
An arbitrary user defined name.

@end table

@subsection Defining new styles
@anchor{Defining new styles}
@noindent
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.

@cindex example
@smallexample

pixmap_path "@i{directory_that_contains_the_pixmap}"
style "custom-button" = "default"
@{
  bg_pixmap[NORMAL]="@i{pixmap_file}"
  bg[ACTIVE]="blue"
@}
class "GtkButton" style "custom-button"

@end smallexample

@noindent
Here is the syntax for defining styles:

@smallexample

sequence-of-style ::=
   @{ style | property @}

style ::=
   style-name[state] = string_literal

style-name ::=
   @i{bg | fg | base | text | bg_pixmap | font_name}

state ::=
   @i{NORMAL | ACTIVE | PRELIGHT | SELECTED | INSENSITIVE}

property ::=
   widget-name::widget-property = value

widget-property ::=
   @i{cursor-aspect-ratio | cursor-color }

@end smallexample

@noindent
The table below describes the meaning of each of these elements:

@table @command
@item bg[@i{state}] = @i{color}
Sets the color used for the background of most visual objects.

@item fg[@i{state}] = @i{color}
Sets the color used for the foreground of most visual objects.

@item base[@i{state}] = @i{color}
Sets the color used for the background of visual objects displaying editable
text, for instance the text editor in GPS.

@item text[@i{state}] = @i{color}
Sets the color used for foreground of visual objects using base for the
background color.

@item bg_pixmap[@i{state}] = @i{pixmap}
Sets a background pixmap to be used in place of the bg color. The special
value @i{"<parent>"} may be used to indicate that the visual object should use
the same background pixmap as its parent. The special value @i{"<none>"} may be
used to indicate no background pixmap.

@item font_name = @i{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. @i{"Sans Italic 10"}.

@item GtkTextView::cursor-aspect-ratio = @i{value}
Width ratio with which to draw the insertion cursor. @i{Value} is a float value
between 0.0 and 1.0. The default value is 0.04.

@item GtkTextView::cursor-color = @i{color}
Color with which to draw insertion cursor

@end table

@noindent
The colors and background pixmaps are specified as a function of the state of
the visual object. The states are:

@table @command
@item NORMAL
A color used for a visual object in its normal state.

@item 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.

@item 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.

@item 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.

@item INSENSITIVE
A color used for the background of visual objects that have been set
insensitive.
@end table

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 @code{#rrrrggggbbbb}, @code{#rrrgggbbb},
@code{#rrggbb}, or @code{#rgb}, where r, g and b
are hex digits, or they can be specified as a triplet @code{@{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.

@subsection Defining new key bindings
@anchor{Defining new key bindings}
@noindent
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.

@smallexample

sequence-of-binding ::=
   @{ binding @}

binding ::=
   @b{bind} "key-name"
   @{
      sequence-of-commands
   @}

sequence-of-commands ::=
   @{ command @}

command ::=
   "command-kind" (parameters)

parameters ::=
   [first-parameter @{, number@}]

widget-name ::=
   @i{GtkButton | GtkDialog | GtkEntry | GtkMenuItem |}
   @i{GtkMenuShell | GtkTextView | GtkTreeView}

command-kind ::=
   @i{move-cursor | page-horizontally | set-anchor | insert-at-cursor |}
   @i{delete-from-cursor | cut-clipboard | copy-clipboard | paste-clipboard |}
   @i{toggle-overwrite | move-focus | activate | select-all | unselect-all |}
   @i{select-cursor-row | toggle-cursor-row | expand-collapse-cursor-row |}
   @i{select-cursor-parent | start-interactive-search | clicked | close |}
   @i{move-current}

first-parameter ::=
   @i{movement-step | count | extend-selection | delete-type | start-editing |}
   @i{logical | expand | expand-all | menu-direction |} string_litteral

number ::=
   [-|+]digit@{digit@}

key-name ::=
   @{modifier@}key

modifier ::=
   <ctrl> | <alt> | <shift>

key ::=
   letter | digit |
   @i{BackSpace | Tab | Return | Pause | Scroll_Lock | Sys_Req | Escape |}
   @i{Delete | Home | Left | Up | Right | Down | Page_Up | Page_Down | End |}
   @i{Insert | Break | Num_Lock |}
   @i{F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F10 | F11 | F12 |}
   @i{Caps_Lock | space | exclam | quotedbl | numbersign | dollar | percent |}
   @i{ampersand | apostrophe | quoteright | parenleft | parenright | asterisk |}
   @i{plus | comma | minus | period | slash | colon | semicolon | less |}
   @i{equal | greater | question | at | bracketleft | backslash |}
   @i{bracketright | underscore | grave | quoteleft | braceleft | bar |}
   @i{braceright}

@end smallexample

@noindent
The list of valid @command{command-kind} values and their parameters depend on
the widget name:

@table @command
@item GtkButton
   Applies to buttons.
   @table @command
   @item clicked ()
      Generate a button click event.
   @end table

@item GtkDialog
   Applies to dialog windows.
   @table @command
   @item close ()
      Close the current dialog box.
   @end table

@item GtkEntry
   Applies to single line text entries.
   @table @command
   @item activate ()
      Activate the text entry.
   @item move-cursor (movement-step, count, extend-selection)
      Move insertion point by count steps. If extend-selection is true,
      create or extend the selection.
   @item insert-at-cursor (string)
      Insert a given text string at the cursor.
   @item delete-from-cursor (delete-type, count)
      Delete count units from the cursor.
   @item cut-clipboard ()
      Cut the current selection to the clipboard.
   @item copy-clipboard ()
      Copy the current selection to the clipboard.
   @item paste-clipboard ()
      Paste the contents of the clipboard.
   @item toggle-overwrite ()
      Toggle the current overwrite mode.
   @end table

@item GtkMenuItem
   Applies to menu items.
   @table @command
   @item activate ()
      Activate the menu item.
   @end table

@item GtkMenuShell
   Applies to menus.
   @table @command
   @item move-current (menu-direction)
      Move the current menu entry to the given direction.
   @end table

@item GtkTextView
   Applies to source and text editors.
   @table @command
   @item move-cursor (movement-step, count, extend-selection)
      Move insertion point by count steps. If extend-selection is true,
      create or extend the selection.
   @item page-horizontally (count, extend-selection)
      Move cursor to the beginning (count=-1) or the end (count=1) of the
      current line.
   @item set-anchor ()
      Move the anchor to the cursor position.
   @item insert-at-cursor (string)
      Insert a given text string at the cursor.
   @item delete-from-cursor (delete-type, count)
      Delete count units from the cursor.
   @item cut-clipboard ()
      Cut the current selection to the clipboard.
   @item copy-clipboard ()
      Copy the current selection to the clipboard.
   @item paste-clipboard ()
      Paste the contents of the clipboard.
   @item toggle-overwrite ()
      Toggle the current overwrite mode.
   @end table

@item GtkTreeView
   Applies to tree and list objects, in particular the Location Tree, the
   Project View, the File View and the VCS Explorer.
   @table @command
   @item move-cursor (movement-step, count)
      Move insertion point.
   @item select-all ()
      Select all rows.
   @item unselect-all ()
      Unselect all rows.
   @item select-cursor-row (start-editing)
      Select or unselect the current row.
   @item toggle-cursor-row ()
      Toggle the selection of the current row.
   @item 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.
   @item select-cursor-parent ()
      Select the parent row of the current selection.
   @item start-interactive-search ()
   @cindex interactive search
   @anchor{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 @key{up} and @key{down} keys to navigate through
      all the items matching the current text.
   @end table
@end table

@noindent
The possible values of the parameters listed above are:

@table @command
@item count
   Signed integer value.

@item string
   Quoted string, e.g @i{"text"}.

@item extend-selection, start-editing, logical, expand, expand-all:
   Boolean value. 0 means false, 1 means true.

@item delete-type
   @table @command
   @item chars
      Delete a given amount of characters.
   @item word-ends
      Delete only the portion of the word to the left/right of cursor if we're
      in the middle of a word.
   @item paragraph-ends
      Delete between cursor and the end (count=1) or beginning (count=-1) of
      current line.
   @item paragraphs
      Delete whole line.
   @item whitespace
      Delete all white spaces around the cursor.
   @end table

@item menu-direction
   @table @command
   @item parent
      Select the parent menu item.
   @item child
      Select the first child menu item.
   @item next
      Select the next (sibling) menu item.
   @item prev
      Select the previous (sibling) menu item.
   @end table

@item movement-step
   @table @command
   @item logical-positions
      Move by forward/back graphemes.
   @item visual-positions
      Move by left/right graphemes.
   @item words
      Move by forward/back words.
   @item display-lines
      Move up/down lines (wrapped lines).
   @item display-line-ends
      Move to either end of a line (wrapped lines).
   @item paragraphs
      Move up/down paragraphs (newline-ended lines).
   @item paragraph-ends
      Move to either end of a paragraph.
   @item pages
      Move by pages.
   @item buffer-ends
      Move to the end (count=1) or to the beginning (count=-1) of the file.
   @end table
@end table

@c --------------------------------------------------------------------
@node Scripting GPS
@section Scripting GPS
@cindex scripts
@c --------------------------------------------------------------------

@menu
* Scripts::
* The GPS Shell::
@c * The Python Interpreter::
@end menu

@node Scripts
@subsection Scripts

@noindent
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,@dots{}

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.

@cindex --load
Scripts can be executed immediately upon startup of GPS by using the
command line switch @code{--load}. Specifying the following command
line:

@smallexample
gps --load=shell:mytest.gps
@end smallexample

will force the gps script @file{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.

@cindex --eval
In line commands can also be given directly on the command line through
@code{--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:

@smallexample
gps --eval=shell:'Entity entity_name file_name; Entity.show %1'
@end smallexample



@node The GPS Shell
@subsection The GPS Shell
@cindex gps shell

@noindent
The GPS shell is a very simple-minded, line-oriented language. It is
accessible through the @code{Shell} window at the bottom of the GPS
window. It is similar to a Unix shell, or a command window on Windows
systems.

Type @code{help} at the prompt to get the list of available commands,
or @code{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.

@smallexample
GPS> Entity my_entity file_name.adb
<Entity_0x09055790>
GPS> Entity.find_all_refs <Entity_0x09055790>
@end smallexample

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 @code{<Entity_0x09055790>} in the example above,
are kept in memory.

@cindex clear_cache command
The GPS shell provides the command @code{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 @code{%1}, @code{%2},@dots{} on the command line. For instance,
the previous example could be rewritten as

@smallexample
GPS> Entity my_entity file_name.adb
<Entity_0x09055790>
GPS> Entity.find_all_refs %1
@end smallexample

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 @code{--eval}
and @code{--load}), or for custom files, @xref{Customizing the Menu
and Tool Bar}.


In future versions of GPS, it will be possible to use more advanced scripting
languages such as @code{Python}.

@c @node The Python Interpreter
@c @subsection The Python Interpreter
@c @cindex python
@c @noindent
@c
@c Python is an interpreted object-oriented language, created by Guido
@c Van Rossum. It is similar in its capabilities to languages such as
@c Perl, Tcl or Lisp. This section is not a tutorial on python
@c programming. See @url{http://www.python.org/doc/current/} to access the
@c documentation for the current version of python.
@c
@c The python shell is accessible through the @code{Python} window at the
@c bottom of the GPS window. However, GPS might not have been compiled
@c with support for python, and therefore python might not be available
@c to you.
@c
@c If a script is executed that requires user input, the whole GPS environment
@c is frozen. This is to prevent the user from selecting a menu that would in
@c turn launch a new python command while the previous one has not finished to
@c execute.
@c
@c Type @code{help(GPS)} to see the list of functions exported by GPS to
@c python. This list is also given in @ref{Python Commands} at the end
@c of this documentation.
@c
@c The same example that was used to show the GPS shell is now done
@c through python. As you can notice, the name of the commands is
@c similar, although they are not run exactly in the same
@c way. Specifically, GPS benefits from the object-oriented aspects of
@c python to create classes and instances of these classes.
@c
@c In the first line, a new instance of the class Entity is created
@c through the @code{create_entity} function. Various methods can then be
@c applied to that instance, including @code{find_all_refs}, which lists
@c all references to that entity in the location window
@c 
@c @smallexample
@c >>> e=GPS.Entity ("entity_name", "file_name.adb")
@c >>> e.find_all_refs()
@c @end smallexample
@c 
@c Python has extensive introspection capabilities. Continuing the
@c previous example, one can find what class @code{e} is an instance of
@c with the following command:
@c 
@c @smallexample
@c >>> help(e)
@c Help on instance of Entity:
@c 
@c <GPS.Entity instance>
@c @end smallexample
@c 
@c It is also possible to find all attributes and methods that can be
@c applied to @code{e}, as in the following example:
@c 
@c @smallexample
@c >>> dir (e)
@c ['__doc__', '__gps_data__', '__module__', 'called_by', 'calls',
@c 'find_all_refs']
@c @end smallexample

@c Note that the list of methods may vary depending on what modules were
@c loaded in GPS, since each module can add its own methods to any class.

@c Finally, the list of all existing modules and objects currently known
@c in the interpreter can be found with the following command:
@c 
@c @smallexample
@c >>> dir ()
@c ['GPS', 'GPSStdout', '__builtins__', '__doc__', '__name__', 'e', 'sys']
@c @end smallexample

@c You can load and execute python scripts with the @code{execfile} command,
@c as in the following example:

@c @smallexample
@c >>> execfile ("test.py")
@c @end smallexample

@c Python supports named parameters. Most functions exported by GPS define
@c names for their parameters, so that you can use this Python's feature, and
@c make your scripts more readable. A notable exception to this rule are the
@c functions that take a variable number of parameters,

@c Using named parameters allows you to specify the parameters in any order
@c you wish.

@c #smallexample
@c >>> e=GPS.Entity (name="foo", file="file.adb")
@c end smallexample

@c --------------------------------------------------------------------
@node Environment
@chapter Environment
@cindex environment
@c --------------------------------------------------------------------

@menu
* Command Line Options::
* Environment Variables::
* Files::
* Reporting Suggestions and Bugs::
* Solving Problems::
@end menu

@node Command Line Options
@section Command Line Options
@cindex command line
@cindex options

@cindex example
@smallexample
Usage:
   gps [options] [-Pproject-file] [source1] [source2] ...
Options:
   --help              Show this help message and exit
   --version           Show the GPS version and exit
   --debug[=program]   Start a debug session and optionally load the
                       program with the given arguments
   --debugger debugger Specify the debugger's command line
   --target=TARG:PRO   Load program on machine TARG using protocol PRO
   --load=lang:file    Execute an external file written in the language lang
   --eval=lang:file    Execute an in-line script written in the language lang

Source files are searched everywhere on the project's source path
@end smallexample

@c --------------------------------------------------------------------
@node Environment Variables
@section Environment Variables
@cindex environment
@cindex environment variables
@c --------------------------------------------------------------------

@noindent
The following environment variables can be set to override some default
settings in GPS:

@table @samp
   @item GPS_ROOT
@cindex GPS_ROOT
Override the default root directory specified when GPS
is built (during the @i{configure} process, see the file @code{INSTALL} in
the GPS sources for more details) to access information such as the location
of the translation files.

   @item GPS_HOME
@cindex GPS_HOME
@cindex Windows
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.

   @item GPS_DOC_PATH
@cindex GPS_DOC_PATH
Set the search path for the documentation. See @ref{Integrated Help} for
more details.

@c Currently disabled, since this is not well supported yet
@c    @item GDK_USE_XFT
@c @cindex GDK_USE_XFT
@c If this variable is set to 1, then the fonts used in most parts of gps will be
@c anti-aliased fonts, provided your Xserver supports the Xft extension, and you
@c have installed anti-aliased fonts on your system, like the true-type fonts
@c available at @url{http://keithp.com/~keithp/truetype.tar.gz}
@c @cindex url

@end table

@c --------------------------------------------------------------------
@node Files
@section Files
@cindex files
@c --------------------------------------------------------------------

@noindent

@table @file
   @item $HOME/.gps
@cindex Windows
@cindex HOME
GPS state directory. Defaults to C:\.gps under Windows systems if HOME is not
defined.

   @item $HOME/.gps/log
@cindex log
@anchor{log file}
Log file created automatically by GPS

   @item $HOME/.gps/aliases
@cindex aliases
File containing the user-defined aliases (@pxref{Defining Text Aliases}).

   @item $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.
@pxref{Customizing the Menu and Tool Bar} and
@pxref{Adding Support for New Languages}.

   @item $HOME/.gps/custom_key
Contains all the key bindings defined in GPS. This file is
automatically created if you have activated the dynamic key bindings feature
(@pxref{Customizing the Menu and Tool Bar}).

   @item $HOME/.gps/debugger.log
@cindex log
@cindex debugger
Log file created by the integrated debugger to trace of communication between
GPS and gdb.

   @item $HOME/.gps/desktop
Desktop file in XML format (using the menu @code{File->Save...->Desktop}),
loaded automatically if found.

   @item $HOME/.gps/gtkrc
@cindex Gtk+
@cindex 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. @xref{Defining New Styles and Key Bindings}.
See also @file{<prefix>/etc/gps/gtkrc}.

   @item $HOME/.gps/history
@cindex history
Contains the state and history of combo boxes (e.g. the
@code{Run->Custom...} dialog).

   @item $HOME/.gps/preferences
@cindex preferences
Contains all the preferences in XML format, as specified in the
preferences menu.

   @item $HOME/.gps/sessions
Directory containing the debugging sessions.

   @item $HOME/.gps/sessions/@i{session}
Each file in the @code{sessions} directory represents a particular session
saved by the user.

   @item $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 @file{$HOME/.gps/log}.

   @item @i{prefix}
The prefix directory where GPS is installed, e.g @file{/opt/gps}.

   @item @i{prefix}/bin
The directory containing the GPS executables.

   @item @i{prefix}/etc/gps
The directory containing global configuration files for GPS.

   @item @i{prefix}/etc/gps/gtkrc
@cindex Gtk+
@cindex gtkrc
The global theme used by the gtk+ library. See also @file{$HOME/.gps/gtkrc}.

   @item @i{prefix}/etc/gps/pangorc
The pango (generic font handling) configuration file.

   @item @i{prefix}/etc/gps/pangox.aliases
File defining font aliases to X font set.

   @item @i{prefix}/lib
This directory contains the shared libraries used by GPS.

   @item @i{prefix}/doc/gps/html
GPS will look for all the documentation files under this directory.

   @item @i{prefix}/doc/gps/examples
This directory contains source code examples.

   @item @i{prefix}/doc/gps/examples/tutorial
This directory contains the sources used by the GPS tutorial.
@ifhtml
@cindex url
See @url{gps-tutorial.html}.
@end ifhtml

   @item @i{prefix}/share/gps/aliases
   @cindex aliases
Directory containing files with system-wide aliases
(@pxref{Defining Text Aliases}).

   @item @i{prefix}/share/gps/customize
Directory containing files with system-wide customizations
(@pxref{Adding Support for New Languages}).

   @item @i{prefix}/share/gps/gps-animation.gif
@cindex gif
Animated image displayed in the top right corner of GPS to indicate that
actions (e.g compilation) are on going.

   @item @i{prefix}/share/gps/gps-splash.jpg
@cindex jpeg
Splash screen displayed by default when GPS is started.

   @item @i{prefix}/share/themes
@cindex Gtk+
@cindex theme
Directory containing the Gtk+ predefined themes.

   @item @i{prefix}/share/make
Directory containing shared makefiles used by the multi-language build
system.

   @item @i{prefix}/share/locale
Directory used to retrieve the translation files, when relevant.

@end table

@c --------------------------------------------------------------------
@node Reporting Suggestions and Bugs
@section Reporting Suggestions and Bugs
@cindex suggestions
@cindex submitting bugs
@c --------------------------------------------------------------------

@noindent
If you would like to make suggestions about GPS, or if you encountered a bug,
please report it to @uref{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
@i{debugger}, @i{compiler}, @i{call graph}) involved.

The files @file{$HOME/.gps/log} and @file{$HOME/.gps/debugger.log} may also
bring some useful information when reporting a bug.

@c --------------------------------------------------------------------
@node Solving Problems
@section Solving Problems
@cindex problems
@cindex solving problems
@c --------------------------------------------------------------------

@noindent
This section addresses some common problems that may arise when using or
installing GPS.

@table @samp

@item 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.

@item GPS crashes whenever I open a source editor
This is usually due to font problems. Editing the file
@file{$HOME/.gps/preferences} and changing the name of the fonts, e.g
changing @i{Courier} by @i{Courier Medium}, and @i{Helvetica} by @i{Sans}
should solve the problem.

@item GPS refuses to start the debugger
@cindex debugger
If GPS cannot properly initialize the debugger (using the menu
@code{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).

@item GPS is frozen during a debugging session
@cindex debugger
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
@key{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
@code{ps} and @code{kill}, or the @code{top} command under Unix,
@cindex Unix
@cindex Windows
and the @code{Task Manager} under Windows: this will terminate your debugging
session, and will unblock GPS.

@item My Ada program fails during elaboration. How can I debug it ?
@cindex -g
@cindex gnatmake
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
@option{-C} switch was used) program, compiled in the usual manner,
and fully debuggable provided that the @option{-g} switch is used on
the @command{gnatlink} command (or @option{-g} is used in the
@command{gnatmake} command itself).

The name of this package containing the main program is
@file{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.

@item 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
@option{-a} and @option{-f} to the @command{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 @file{Makefile.adalib}
that can be found in the adalib directory of your GNAT installation and
specify e.g @option{-g -O2} for the @option{CFLAGS} switches.

@item The GPS main window is not displayed
If when launching GPS, nothing happens, you can try to rename the @file{.gps}
directory (see @ref{Files}) to start from a fresh set up.

@end table

@c --------------------------------------------------------------------
@c @node Python Commands
@c @appendix Python Commands
@c --------------------------------------------------------------------

@c This section lists all functions that GPS exports to python. This is
@c the result of interactively running the following commands in the
@c python interpreter:

@c @smallexample
@c >>> e=file("/tmp/foo", "w")
@c >>> sys.stdout=e
@c >>> help(GPS)
@c >>> e.flush()
@c >>> sys.stdout=sys.__stdout__
@c @end smallexample
@c 
@c Here is the list:
@c 
@c @example
@c @end example
@c 
@c 
@c --------------------------------------------------------------------
@unnumbered Index
@printindex cp

@ifinfo
@contents
@end ifinfo

@bye
