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

@c For uniformity, screenshots are generated using the following setup:
@c   - Under Windows XP, using the default XP theme
@c   - Using the standard Windows screen or window capture
@c     (using e.g Ctrl-PrntScrn)
@c
@c   - Save the resultat image (if needed, truncated to show only relevant
@c     items) in jpeg format, quality 95%

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

@set GPS
@include version.texi

@titlepage

@flushleft
@title{Using GPS}
@end flushleft
@sp 1
@flushright
@titlefont{The GNAT Programming Studio}
@end flushright
@sp 2
@subtitle Version @value{GPSVersion}
@subtitle Document revision level $Revision: 165232 $
@subtitle Date: $Date: 2010-10-01 12:54:37 +0200 (Fri, 01 Oct 2010) $
@author AdaCore

@page
@vskip 0pt plus 1filll

Copyright @copyright{} 2001-2010, AdaCore.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
``Using the GNAT Programming Studio'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.

@end titlepage

@ifnottex
@ifhtml
@node Top, Introduction,,
@top Using the GNAT Programming Studio
@end ifhtml
@ifnothtml
@node Top, Introduction, (dir), (dir)
@top Using the GNAT Programming Studio
@end ifnothtml

Version @value{GPSVersion}

Date: $Date: 2010-10-01 12:54:37 +0200 (Fri, 01 Oct 2010) $

Copyright @copyright{} 2001-2010, AdaCore

@menu
* Introduction::
* Description of the Main Windows::
* Online 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::
* Using GPS for Remote Development::
* Customizing and Extending GPS::
* Environment::
* GNU Free Documentation License::
* Index table::

@detailmenu

 --- The Detailed Node Listing ---

Description of the main windows
* The Welcome Dialog::
* The Tip of the Day::
* The Menu Bar::
* The Tool Bar::
* The Work Space::
* The Project View::
* The File View::
* The Entity View::
* The Window View::
* The Outline View::
* The Clipboard View::
* The Callgraph View::
* Bookmarks::
* The Messages Window::
* The Shell and Python Windows::
* The Locations View::
* The Status Line::
* The Task Manager::

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

Multiple Document Interface
* Selecting Windows::
* Closing Windows::
* Splitting Windows::
* Floating Windows::
* Moving Windows::
* Perspectives::

Editing Files
* General Information::
* Editing Sources::
* The File Selector::
* Menu Items::
* Rectangles::
* Recording and replaying macros::
* Contextual Menus for Editing Files::
* Handling of case exceptions::
* Refactoring::
* Using an External Editor::
* Using the Clipboard::
* Saving Files::
* Remote Files::

Refactoring
* Rename Entity::
* Name Parameters::
* Extract Subprogram::

Source Navigation
* Support for Cross-References::
* The Navigate Menu::
* Contextual Menus for Source Navigation::
* Navigating with hyperlinks::
* Highlighting dispatching calls::

Project Handling
* Description of the Projects::
* Supported Languages::
* Scenarios and Configuration Variables::
* Extending Projects::
* Project View::
* Disabling Project Edition Features::
* The Project Menu::
* The Project Wizard::
* The Project Dependencies Editor::
* The Project Properties Editor::
* The Switches Editor::
* The Project Browser::

Searching and Replacing

Compilation/Build
* The Build Menu::
* The Target Configuration Dialog::
* The Build Mode::
* Working with two compilers::

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::
* Customizing the Debugger::

Version Control System
* The VCS Explorer::
* The VCS Activities::
* The VCS Menu::
* The Version Control Contextual Menu::
* Working with global ChangeLog file::
* The Revision View::

Tools
* The Tools Menu::
* Visual Comparison::
* Code Fixing::
* Documentation Generation::
* Metrics::
* Code Coverage::

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

Using GPS for Remote Development
* Requirements::
* Setup the remote servers::
* Setup a remote project::
* Limitations::

Customizing and Extending GPS
* The Preferences Dialog::
* GPS Themes::
* The Key Manager Dialog::
* The Plug-ins Editor::
* Customizing through XML and Python files::
* Adding support for new tools::
* Customization examples::
* Scripting GPS::
* Adding support for new Version Control Systems::
* The Server Mode::
* Adding project templates::

Customizing through XML and Python files
* Customization files and plugins::
* Defining Actions::
* Macro arguments::
* Filtering actions::
* Adding new menus::
* Adding contextual menus::
* Adding tool bar buttons::
* Binding actions to keys::
* Preferences support in custom files::
* Creating themes::
* Defining new search patterns::
* Adding support for new languages::
* Defining text aliases::
* Defining project attributes::
* Adding casing exceptions::
* Adding documentation::
* Adding stock icons::
@c * Defining a documentation format::
* Remote programming customization::
* Customizing build Targets and Models::

Adding support for new tools
* Defining supported languages::
* Defining default command line::
* Defining tool switches::
* Executing external tools::

Customization examples
* Menu example::
* Tool example::

Scripting GPS
* Scripts::
* Scripts and GPS actions::
* The GPS Shell::
* The Python Interpreter::
* Subprogram parameters::
* Python FAQ::
* Hooks::

Python FAQ
* Hello World! in python::
* Spawning external processes::
* Redirecting the output of spawned processes::
* Contextual menus on object directories only::
* Redirecting the output to specific windows::
* Reloading a python file in GPS::
* Printing the GPS Python documentation::
* Automatically loading python files at startup::
* Hiding contextual menus::
* Creating custom graphical interfaces::

Environment
* Command Line Options::
* Environment Variables::
* Running GPS on Mac OS X::
* Files::
* Reporting Suggestions and Bugs::
* Solving Problems::

@end detailmenu
@end menu

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
``Using the GNAT Programming Studio'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.

@end ifnottex

@iftex
@contents
@end iftex

@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,
entity view, etc@dots{}; fully integrated visual debugger; generic
version control system, providing access to CVS, Subversion, ClearCase, GIT,
and any other via xml plug-ins; 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 and key manager dialogs;
a second level, which allows you to customize your menu items, tool bar and key
bindings; a third level, which allows you to automate processing through
scripts (via xml and python scripting). See @ref{Customizing and Extending GPS}
for more details.

GPS also interacts with most versions of command-line tools such as
gcc, gdb, gnatmake, gcov, etc@dots{}.

@image{main-gps, 9.7cm}

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

@menu
* The Welcome Dialog::
* The Tip of the Day::
* The Menu Bar::
* The Tool Bar::
* The Work Space::
* The Project View::
* The File View::
* The Entity View::
* The Window View::
* The Outline View::
* The Clipboard View::
* The Callgraph View::
* Bookmarks::
* The Messages Window::
* The Shell and Python Windows::
* The Locations View::
* The Execution Window::
* The Status Line::
* The Task Manager::
@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 Create new project from template
If you select this option and then click the @code{OK} button, GPS will
launch an assistant to create a project using one of the predefined project
templates.

@item Start with default project in directory
@cindex project
If you select this option and click on the @code{OK} button, GPS will
first look for a project called @file{default.gpr} in the current directory
and load it if found. Otherwise, it will copy in
the current directory the default project found under
@file{<prefix>/share/gps/default.gpr} and load it.
GPS will remove this copy when exiting or loading another project, if the
copy has not been modified during the session.

If the current directory is not writable, GPS will instead load directly
@code{<prefix>/share/gps/readonly.gpr}. In this case, GPS will work in a
degraded mode, where some capabilities will not work (such as building and
source navigation).

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

Several kinds of wizard are available. Depending on the kind of project,
you will get asked different type of information. In the end, GPS will create
one or more project files, and automatically load them.

One of the wizard, "From existing Ada sources", will try and import a set of
sources and object files, and attempt to create one or more project files so
that building your application through these project files will put the objects
in the same directory they are currently in. If you have not compiled your
application when launching this wizard, GPS will create a single project file
and all object files will be put in the same object directory. This is the
prefered method when importing sources with duplicate file names, since the
latter is only authorized in a single project file, not across various project
files.

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

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

@c --------------------------------------------------------------------
@node The Tip of the Day
@section The Tip of the Day
@cindex tip of the day
@c --------------------------------------------------------------------

@noindent
This dialog displays short tips on how to make the most efficient use of
GPS. You can click on the @code{Previous} and @code{Next} buttons to access
all tips, and close the dialog by either clicking on the @code{Close} button
or pressing the @key{ESC} key.

You can also disable this dialog by unchecking the @code{Display Tip of the
Day on startup} check box. If you would like to reenable this dialog, you
can go to the @code{Edit->Preferences} dialog.
@cindex preferences
@xref{The Preferences Dialog}.

@iftex
@cindex screen shot
@image{tip-of-the-day, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{tip-of-the-day}
@end ifhtml

@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 or when using the special
@key{open contextual menu} key on most PC keyboards.

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 SPARK
If the SPARK toolset is installed on your system and available on your
PATH, then this menu is available. See
@code{Help->SPARK->Reference->Using SPARK with GPS} for more details.

@item CodePeer
If the CodePeer toolset is installed on your system and available on your PATH,
then this menu is available. See your CodePeer documentation for more details.

@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; go to previous/next location;
@cindex build
select build mode, compile file, build project, clean project;
@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 the 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 View
@section The Project View
@cindex project view
@cindex project view
@cindex project
@c --------------------------------------------------------------------

@noindent
The project view provides a representation of the various components of your
project hierarchy, as listed below.
It is displayed by default on the left side of the main window, and can
be selected by using the @code{Project->Project View} or
@code{Tools->Views->Project} menu items.

@cindex drag-n-drop
Under Windows, it is possible to drop files (coming e.g. from the Explorer)
in the project view with the following behavior: a project file dropped
will be loaded; any other file will be opened in a new source editor.

@iftex
@cindex screen shot
@image{project-view, 6.7cm}
@end iftex

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

@cindex interactive search
The project view, as well as the file and outline view provide an
interactive search capability allowing you to quickly
search in the information currently displayed. The default key
to start an interactive search is @key{control-f}.
@anchor{Interactive Search}
This will open a small window
at the bottom of the 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.

The various components that are displayed are:

@table @b
@item projects
@cindex project view
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} displays this project hierarchy: the top node
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 view,
at the top level. This display might be useful for deep project hierarchies, to
make it easier to find projects in the project view.

@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 a pen 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, or save it automatically, if the corresponding preference
is saved.

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

@cindex Show absolute paths
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.

@cindex Show hidden directories
The contextual menu entry @code{Show hidden directories} can be used to filter
the directories considered as hidden. This can be used to not display the
version control directories like @file{CVS} or @file{.svn} for example.

@item files
@cindex file
@cindex file view
The source files themselves are stored in the directories, and
displayed under the corresponding nodes. Note that
only the source files that actually belong to the
project (i.e. are written in a language supported by that project and
follow its naming scheme) are actually visible.
For more information on supported languages, @xref{Supported Languages}.

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

If you left click on a file and keep the button pressed, you can drop it
anywhere in GPS to open an editor at that location.

@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 a file, or simple clicking on any entity will open
a source editor and display respectively the first line in this file
or the line on which the entity is defined.

You can also drag a file anywhere into GPS. This will open a new editor
if the file is not already edited, or move the existing editor otherwise.
If you press @key{shift} at the same time, and the file is already edited,
a new view of the existing editor is created instead.

@c ??? Following is currently disabled
@c Moving the mouse over the different components displayed on the
@c project view will open tooltips with some more information
@c depending on the type of component:

@c @table @b
@c @item projects
@c The tooltip contains the project full pathname.

@c @item directories
@c The tooltip contains the directory full pathname and the project name in
@c which it is defined.

@c @item files
@c The tooltip contains the base filename and the project name in
@c which it is defined.

@c @item entities
@c The tooltip contains the entity name and parameters for routines followed
@c by the location in the form filename:line where it is declared.
@c @end table

@cindex search
@cindex find
If you open the search dialog through the @code{Navigate->Find or Replace...}
menu, you have the possibility to search for anything in the project view,
either a file or an entity. Note that searching for an entity can be slow
if you have lots of files, and/or big files.

@cindex view
@cindex locate in project view
A contextual menu, named @code{Locate in Project View}, is also provided when
inside a source editor. This will automatically search for the first entry for
this file in the project view. 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 window
called the @code{Scenario View}. These variables are called
@code{Configuration Variables}, since they provide various scenarios for
the same set of project files.

@iftex
@cindex screen shot
@image{scenario-view, 6.7cm}
@end iftex

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

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{Project->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.


@subsection Icons for source language entities
@cindex icons for source language entities

@noindent
Entities in the source code are presented with representative icons
within the various GPS views (the @emph{Outline}, @emph{Project},
and @emph{Entity} views, for example).
These icons indicate both the language categories of the entities, such as
packages and methods, as well as compile-time visibility.
In addition, the icons distinguish entity
declarations from other entities.  The same icons are used for all
programming languages supported by the viewers, with language-specific
interpretations for both compile-time visibility and recognizing
declarations.

There are five language categories used for all supported languages:
@emph{package}, @emph{subprogram}, @emph{type}, @emph{variable}, and
@emph{generic}.  The icons
corresponding to these language categories are as follows.

@itemize @bullet
@item
The @emph{package} category's icon is a square.

@iftex
@image{square_x}
@end iftex
@ifhtml
@image{square_x}
@end ifhtml

@item
The @emph{subprogram} category's icon is a circle.

@iftex
@image{circle_x}
@end iftex
@ifhtml
@image{circle_x}
@end ifhtml

@item
The @emph{type} category's icon is a triangle.

@iftex
@image{triangle_x}
@end iftex
@ifhtml
@image{triangle_x}
@end ifhtml

@item
The @emph{variable} category's icon is a dot.

@iftex
@image{dot_x}
@end iftex
@ifhtml
@image{dot_x}
@end ifhtml

@item
The @emph{generic} category's  icon is a diamond.

@iftex
@image{diamond_x}
@end iftex
@ifhtml
@image{diamond_x}
@end ifhtml
@end itemize

@noindent
These basic icons are enhanced with decorators, when appropriate, to
indicate compile-time visibility constraints and to distinguish
declarations from completions. For example, the icons for entity
declarations have a small ``S'' decorator added, denoting a ``spec''.

With respect to compile-time visibility, icons for ``protected''
and ``private''
entities appear within an enclosing box indicating a visibility
constraint. For entities with ``protected'' visibility, this enclosing box
is colored in gray. ``Private'' entities are enclosed within a red box.
The icons for ``public'' entities have no such enclosing box. For example,
a variable with ``private'' visibility would be represented by an icon
consisting of a dot enclosed within a red box.

These additional decorators are combined when appropriate. For example,
the icon corresponding to the ``private'' declaration of a ``package''
entity would be a square, as for any package entity, with a small ``S''
added, all enclosed within a red box.

Language constructs are mapped to the categories in a language-specific
manner.  For example, C++ namespaces and Ada packages correspond to the
@emph{package} category.  C functions and Ada subprograms correspond to the
@emph{method} category, and so on.  The @emph{generic} category is a
general category representing other language entities, but note that not
all possible language constructs are mapped to categories and icons.  (Note
also that the @emph{generic} category does not correspond to Ada generic
units or C++ templates.)

The names of the categories should not be interpreted literally in terms
of language constructs because the categories are rather general, in
order to limit the number used. The @emph{variable} category includes both
constants and variables in Ada, for example. Limiting the number of
categories maintains a balance between presentation complexity and the
need to support distinct programming languages.

Icons for a given entity may appear more than once within a view. For
example, an Ada private type will have both a partial view in the
visible part of the enclosing package as well as a full view in the
private part of the package. Two triangle icons will therefore appear
for the two occurrences of the type name, one with the additional
decorator indicating the ``private'' compile-time visibility.

@c --------------------------------------------------------------------
@node The File View
@section The File View
@cindex File View
@c --------------------------------------------------------------------

@noindent
In addition to the @code{Project View}, GPS also provides a
@code{File View} through the @code{Tools->Views->Files} menu.

@iftex
@cindex screen shot
@image{file-view, 6.7cm}
@end iftex

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

In this view, directories are displayed exactly as they are organized
physically on the disk (including Windows drives).

By default, the @code{File View} will display all the files that 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 by using the contextual menu @code{Show files from project only}.

Each source file can also be explored as described in
@ref{The Project View}. Drag and drop of files is also possible from the
files view, to conveniently open a file.

The contextual menu also allow you to create, rename and delete files and
directories. Some of those operations are also available from the Project View.

@c --------------------------------------------------------------------
@node The Entity View
@section The Entity View
@cindex Entity View
@c --------------------------------------------------------------------

@noindent
GPS provides an @code{Entity View} which allows you to browse and quickly find
 all Ada entities referenced in the currently loaded project hierarchy. This
 view can be accessed through the @code{Tools->Views->Entities} menu.

@iftex
@cindex screen shot
@image{entity-view, 6.7cm}
@end iftex

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

This view is divided in three parts: a @code{Pattern} entry, a tree view, and
 a documentation view.

To query an entity, enter a search pattern in the @code{Pattern} entry. The
tree view then shows a list of all known entities which start with this
pattern. When an entry is selected in the tree, the documentation view displays
the documentation corresponding to the selected entity.

When the @code{File View} has the focus, using the up/down arrow keys changes
the selection in the tree, and pressing the Enter key opens an editor to the
declaration of the selected entity. It is also possible to jump to this
location by double-clicking on the line in the tree, or by clicking on the
hyperlink in the documentation view.

Note that the view shows the entities that are currently loaded in memory, see
  @ref{Support for Cross-References}.

@c --------------------------------------------------------------------
@node The Window View
@section The Window View
@cindex Window View
@c --------------------------------------------------------------------

@noindent
The @code{Window View} displays the currently opened windows.
It is opened through the @code{Tools->Views->Windows} menu.

It can display the opened windows in one of two ways:
@itemize @bullet
@item Sorted alphabetically
@item Organized by notebooks, as in the GPS window itself. This latter view
 is mostly useful if you have lots of windows open
@end itemize

The mode is selected through the contextual menu.

You can also choose, through this contextual menu, whether only the source
editors should be visible, or whether all windows should be displayed.

This window allows you to quickly select and focus on a particular window,
by clicking on the corresponding line with the left mouse button. If you
click and leave the mouse button pressed, this starts a drag and drop
operation so that you can also move the window to some other place in the
desktop (see the description of the MDI earlier in this document).

Multiple windows can be selected by clicking with the mouse while pressing
the control or shift keys. The Window view provides a contextual menu to
easily close all selected windows at once, which is a very fast way to
cleanup your desktop after you have finished working on a task.

@c --------------------------------------------------------------------
@node The Outline View
@section The Outline View
@cindex Outline View
@c --------------------------------------------------------------------

@noindent
The Outline View, which you can choose to activate through the
@code{Tools->Views->Outline} menu, shows the contents of the current file.

@iftex
@cindex screen shot
@image{outline-view, 10.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{outline-view}
@end ifhtml

The exact meaning of this depends on the language you are seeing. For
Ada, C and C++ files, this is the list of entities that are declared at
the global level in your current file (Ada packages, C++ classes,
subprograms, Ada types, @dots{}).

Clicking on any entity in this view will automatically jump to the right
line in the file, including if your file has been slightly modified since
the outline view was last refreshed.

To refresh the contents of the view, select the @code{Refresh}
entry in the contextual menu (right-click anywhere in the outline view).
The Outline View is updated automatically after editing, saving the file, or
switching to a different editor.

There are several preferences associated with the outline view,
@xref{Outline Preferences}.

@c --------------------------------------------------------------------
@node The Clipboard View
@section The Clipboard View
@cindex clipboard view
@c --------------------------------------------------------------------

@noindent
GPS has an advanced mechanism for handling copy/paste operations.

When you select the menus @code{Edit->Copy} or @code{Edit->Cut}, GPS adds the
current selection to the clipboard. As opposed to what lots of applications
do, it doesn't discard the previous contents of the clipboard, but save it for
future usage. It saves a number of entries this way, up to 10 by default.
This value is configurable through the @code{Clipboard Size} preference.

When you select the menu @code{Edit->Paste}, GPS will paste the last entry
made in the clipboard at the current location in the editor.

If you immediately select @code{Edit->Paste Previous}, this newly inserted
text will be removed, and GPS will instead insert the second to last entry
added to the clipboard. You can keep selecting the same menu to get access
to older entries.

This is a very powerful mechanism, since it means you can copy several distinct
lines from a place in an editor, move to an other editor and paste all these
separate lines, without having to go back and forth between the two editors.

The @code{Clipboard View} provides a graphical mean of seeing what is currently
stored in the clipboard. It appears as a list of lines, each of which is
associated with one level of the clipboard. The text that shows in these lines
is the first line of the selection at that level that contains non blank
characters. Leading characters are discarded. @code{[...]} is prepended
or appended in case the selection has been truncated.

If you bring the mouse over a line in the @code{Clipboard View}, a tooltip will
pop up showing the entire selection corresponding to the line by opposition to
the possibly truncated one.

In addition, one of the lines has an arrow on its left. This indicates the
line that will be pasted when you select the menu @code{Edit->Paste}. If you
select instead the menu @code{Edit->Paste Previous}, then the line below that
one will be inserted instead.

If you double-click on any of these lines, GPS will insert the corresponding
text in the current editor, and make the line you clicked on the current line,
so that selecting @code{Edit->Paste} or the equivalent shortcut will now
insert that line.

The contextual menu in the clipboard view provides one entry, which is
@code{Append To Previous}. If you select this entry, the select line will
be append to the one below, and removed from the clipboard. This means that
selection @code{Edit->Paste} will in fact paste the two entries at the same
time. This is in particular useful when you want to copy lines from separate
places in the initial file, merge them, and then paste them together one or
more times later on, through a single operation.

The Clipboard View content is preserved between GPS sessions. As an exception,
huge entries are removed and replaced with an entry saying "[Big entry has
been removed]".

@c --------------------------------------------------------------------
@node The Callgraph View
@section The Callgraph View
@cindex callgraph
@c --------------------------------------------------------------------

@noindent
The callgraph view plays a role similar the callgraph browser. They display
the same information about entities, but in two different ways: the callgraph
view displays the information in a tree, easily navigable and perhaps easier
to manipulate when lots of entities are involved; the callgraph browser
displays the information as graphical boxes that can be manipulated on the
screen, and is best suited to generate a diagram that can be later exported
to your own documents.

This callgraph view is used to display the information about what subprograms
are called by a given entity, and, opposite, what entities are calling a
given entity.

Some references might be reported with an additional " (dispatching)" text.
In such a case, this indicates that the call to the entity is not explicit
in the sources, but could occur through dynamic dispatching. This of course
depends on what arguments are passed to the caller at run time, and it is
possible that the subprogram is in fact never dispatched to.

This view is automatically displayed when you select one of the contextual
menus @code{... calls} and @code{... is called by}. Every time you
select one of these menus, a new view is opened to display that entity.

Whenever you expand a node from the tree by clicking on the small expander
arrow on the left of the line, further callgraph information is computed for
the selected entity, which makes it very easy to get information for a full
callgraph tree.

Closing and expanding a node again will recompute the callgraph for the
entity.

On the right side of the main tree, a list displays the locations of calls for
the selected entity. Clicking on entries in this list opens editors showing
the corresponding location.

The Callgraph View supports keyboard navigation: @code{Up} and @code{Down}
keys navigate between listed locations, @code{Left} collapses the current
level, @code{Right} expands the current level, and @code{Return} jumps to the
currently selected location.

The callgraph view is automatically saved in the desktop, and restored
the next time you restart GPS. However, the information displayed in these
might no longer be accurate at this stage, since it shows the status of the
callgraph during the last GPS session.

Left-clicking on a line in the Call Tree brings up a contextual
menu with the following entries:

@table @b
@item Collapse all
Collapse all the entities in the Callgraph View.

@item Remove entity
Remove the selected entity from the Callgraph View.

@item Clear Call Trees
Remove all entries from the Callgraph View.

@end table

@c --------------------------------------------------------------------
@node Bookmarks
@section Bookmarks
@cindex bookmark
@c --------------------------------------------------------------------

@noindent
Bookmarks are a convenient way to remember places in your code or in your
environment so that you can go back to them at any point in the future.
These bookmarks are saved automatically whenever they are modified, and
restored when GPS is reloaded, so that they exist across GPS sessions.

Bookmarks will automatically remember the exact location in an editor, not
in terms of line/column, but in terms of which word they point to. If you
modify the file through GPS, the bookmark will be automatically updated to
keep refering to the same place. Likewise if you close and reopen the file.
However, when the file is modified outside of GPS, the bookmark will not be
aware of that change, and will thus reference another place in the file.

The menu @code{Edit->Create Bookmark} allows you to create a bookmark
at the current location (either in the editor, or the browser for instance).

All the bookmarks you have created will be visible in the
@code{Tools->Views->Bookmarks} window. Clicking on the small icon to the left
side of each line will immediately jump to that bookmark.

You can rename a bookmark so that it is easier to remember what it refers to.
To do so, open the Bookmarks window, and click twice on the line of the
bookmark. This will change the way the name is displayed, so that you can edit
it in place. Press @key{enter} when you are done modifying the name.

You can delete an existing bookmark by right clicking on the line, and
select @code{Delete bookmark} in the contextual menu.

@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
@ref{The Shell and Python Windows}.

@c --------------------------------------------------------------------
@node The Shell and Python Windows
@section The Shell and Python Windows
@cindex python window
@cindex shell
@cindex shell 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.

An OS shell window is now also available in GPS, providing a simple access
to the underlying OS shell as defined by the @code{SHELL} or @code{COMSPEC}
environment variables.

To show the shell consoles, select the menu @code{Tools->Consoles}.

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 View
@section The Locations View
@cindex location
@cindex locations view
@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 Locations View 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. Placing the mouse over an item
automatically pop up a tooltip window with full text of the item if this
text can't be completely shown in the window.

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

Closing the Locations view will remove from the editors locations that
are also visible in the Locations view.
If the Locations View is present when exiting GPS and the desktop is saved,
the locations will be saved as part of the desktop for the current project,
and will be loaded the next time GPS is started on the same project.

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

Left-clicking on a line in the Location Tree brings up a contextual
menu with the following entries:

@table @b
@item Filter panel
Controls availability of the filter panel at the bottom of the window.

@item Sort by subcategory
Toggle the sorting of the entries by sub-categories. This is useful,
for example, for separating the warnings from the errors in the build
results.

@item Expand category
Expand all the files in the current categories.

@item Collapse all
Collapse all the categories in the Locations View

@item Remove category/file/message
Remove the selected category, file or message from the Locations View.
Selected message can be removed using @code{Locations view->Remove message}
key binding also.

@item Jump to location
Open the location contained in the message, if any.

@item Clear Locations View
Remove all entries from the Locations View.

@end table

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.

The filter panel can be used to filter messages which match (or do not
match) a text pattern or regular expression. As soon as you type in the text
entry, the filter is enabled. If you clear the text, the filter is disabled.
The @code{Close} button on the filter panel hides it and cancels the filter.
The @code{Regexp} check button specifies how to use the filter text entry:
as plain text or regular expression.
The @code{Hide matched} check button reverts the filter,
e.g. switch between matching and non-matching items.

@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 (displayed only when background tasks are
running).

@cindex build
The progress bar is used to display information about on going
operations such as builds, searches, or VCS commands. These tasks
operate in the background, and can be paused/resumed by double clicking
on the progress bar: this will open @ref{The Task Manager}.
In addition, you can click on the @i{close} icon on the left of the
progress bar to interrupt the running task.

@c --------------------------------------------------------------------
@node The Task Manager
@section The Task Manager
@cindex tasks
@cindex background tasks
@cindex task manager
@c --------------------------------------------------------------------

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

The Task Manager is opened by double clicking on the progress bar or
using the @code{Tools->Views->Tasks} menu, and can be put anywhere in
your desktop.

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

When exiting GPS, if there are tasks running in the Task Manager, a window
will display those tasks. You can also bring up a contextual menu on the
items in this window.
You can force the exit at any time by pressing the confirmation button, which
will kill all remaining tasks, or continue working in GPS by pressing the
Cancel button.

@iftex
@cindex screen shot
@image{task-manager, 9cm}
@end iftex

@ifhtml
@cindex screen shot
@image{task-manager}
@end ifhtml

@c --------------------------------------------------------------------
@node Online Help
@chapter Online Help
@cindex Online 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 welcome page
giving a few starting points in the online help.

Online help for the GNAT tools is available from the @code{Help} menu item.
GPS launches an external html browser to view these pages. (See
 @ref{The Preferences Dialog} on how to configure this under Unix. Under
Windows systems, the default HTML browser is used.)

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

@table @b

@item Welcome
Open the GPS Welcome page.

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

@item GPS
Submenu containing GPS documentation items.

@item GNAT Runtime
Submenu referencing all GNAT run-time files available, and a direct access
to the corresponding specs containing embedded documentation.

@item Python extensions
Gives access to the GPS API available via python.

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

@node Adding New Help Files
@section Adding New Help Files
@cindex gps_index.xml
@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). In addition, the
default directory @code{<prefix>/share/doc/gps/html} is also 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.

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

@smallexample
GPS.add_doc_directory ("/home/foo")
@end smallexample

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

The format of these index files is specified in @pxref{Adding documentation}.

@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::
* Splitting Windows::
* Floating Windows::
* Moving Windows::
* Perspectives::
@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,
views, @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.

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, one small
button is displayed, looking like a cross. Clicking on
this button will close the window.

An alternative way to close the window is to double-click on the icon
to the left of the title bar of the window. Not all windows have such
an icon, but editors do for instance.

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

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

Finally, a window can be closed by right-clicking in the associated
notebook tab (if the tabs are visible), and select @code{Close} in the
contextual menu.

In the notebook tab (when you are in an editor), you will also find a
@code{Close all other editors} menu, which, as its name implies, will
keep a single editor open, the one you are clicking on.

@c --------------------------------------------------------------------
@node Splitting Windows
@section Splitting Windows
@cindex Splitting
@c --------------------------------------------------------------------

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

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

You may want to bind the key shortcuts to the menus
@code{Window->Split Horizontally}
as well as @code{Window->Split Vertically} using
the key manager. In addition, if you want to
achieve an effect similar to e.g. the standard Emacs behavior (where
@key{control-x 2} splits a window horizontally, and @key{control-x 3} splits
a window vertically), you can use the key manager
(@pxref{The Key Manager Dialog}).

@ref{Moving Windows} will show how to do the splitting through drag-and-drop
and the mouse, which in general is the fastest way to do.

Several editors or browsers can be put in the same area of the MDI. In such
a case, they will be grouped together in a notebook widget, and you can
select any of them by clicking on the corresponding tab. Note that if there
are lots of windows, two small arrows will appear on the right of the tabs.
Clicking on these arrows will show the remaining tabs.

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

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

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

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

@noindent
As we have seen, the organization of windows can be changed at any time
by selecting a notebook containing several editors or browsers, and selecting
one of the Split menus in the @code{Window} menu.

@cindex drag-n-drop
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.

If the window is inside a notebook, you can also choose to select the
notebook tab to start dragging the window around. In such a case, the windows
within the notebook can also be reordered: select the tab, then start moving
left or right to the new position the window should have. Note that your mouse
must remain within the tab area, since otherwise GPS will enter in the mode
where the window can be put in other notebooks.

If you want to move a window to another notebook by dragging its tab, you
should first move out of the tab area (vertically in general), and then
anywhere in GPS. That's to distinguish between the mode where you want to
reorder tabs and the mode where you want to move windows.

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

If you move your mouse all the way to the side of the desktop, and then drop
the window, that window will occupy the full width (resp. height) of the
desktop on that side.

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

@table @b
@item Inside the MDI
The location of the current window is indicated by a dashed rectangle, and
the window you are dragging will be positioned at the same location as that
rectangle: either on top of the window on which you dropped it (therefore they
will both be put inside a notebook), or to one of the sides of that window,
splitting as needed.

@item System window
If you drop a window outside of GPS (for
instance, on the background of your screen), the window will be floated.

@end table

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

If you maintain the @key{control} key pressed while dropping the window,
all the windows that were in the same notebook are moved, instead of the
single one you selected. This is the fastest way to move a group of windows
to a new location, instead of moving them one by one.

@c --------------------------------------------------------------------
@node Perspectives
@section Perspectives
@cindex perspectives
@c --------------------------------------------------------------------
@noindent

GPS supports the concept of perspectives. These are activity-specific
desktops, each with their own set of windows, but sharing some common
windows like the editors.

Depending on the activity you want to perform (debugging, version control,...)
you could switch to another perspective. For instance, in the context of the
debugger, the new perspective would by default contain the call stack window,
the data window, the debugger consoles,@dots{} each at your favorite location.
Whenever the debug starts, you therefore do not have to open these windows
again.

The perspectives have names, and you switch perspectives by selecting the
menu /Window/Perspectives/. You can also create a new perspective by
selecting the menu /Window/Perspectives/Create New.

GPS will sometimes automatically change perspectives. For instance, if you
start a debugger, it will switch to the perspective called "Debug" (if it
exists). When the debugger terminates, you are switched back to the
"Default" perspective (again, if it exists).

When you leave a perspective, GPS automatically saves its contents (which
windows are opened, their location,@dots{}), so that when you are going back
to the same perspective you find the same layout.

Likewise, when GPS exits, it will save the layout of all perspectives into
a file called @file{perspectives.xml}, so that it can restore them when you
restart GPS. This behavior is controlled by the "Save desktop on exit"
preference, and can be disabled.

One of the difficulties in working with perspectives is knowing which
windows will be preserved when you switch to another perspective, and which
windows will be hidden. There is a central area where all preserved windows
are found. Typically, it only contains editors (including if you have split
them side by side for instance). If you drag and drop another window on top
or to the sides of an editor, that window will be preserved when changing
perspectives, unless it was already found elsewhere in the new perspective.
The small tooltip that appears on the screen while you drag and drop will
tell you whether the window (if dropped at the current location) will be
visible in other perspectives or not.

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

@menu
* General Information::
* Editing Sources::
* The File Selector::
* Menu Items::
* Rectangles::
* Recording and replaying macros::
* Contextual Menus for Editing Files::
* Handling of case exceptions::
* Refactoring::
* Using an External Editor::
* Using the Clipboard::
* Saving Files::
* Remote Files::
@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 Speed Column
This column, when visible, is located on the left of the editor. It allows you
to view all the highlighted lines in a file, at a glance. For example, all the
lines containing compilation errors are displayed in the Speed Column.
See @ref{The Preferences Dialog} for information on how to customize the
behavior of the Speed Column.

@item A status bar
Giving information about the file. It is divided in two sections, one
on the left and one on the right of the window.

@table @i
@item The left section

The first box on the left shows the current subprogram name for languages
that support this capability. Currently @code{Ada}, @code{C} and @code{C++}
have this ability. See @ref{The Preferences Dialog} to enable or
disable this feature.

@item The right section

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 current editing mode. This is either
@i{Insert} or @i{Overwrite} and can be changed using the insert
keyboard keys by default.

The third 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 fourth 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 fifth box displays the position of the cursor in the file by a line and
a column number.
@end table

@item A contextual menu
Displayed when you right-click on any area of the source editor.
See in particular @ref{Contextual Menus for Source Navigation}
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.

By default, GPS knows about many languages. You can also easily add support
for other languages through XML files. Most languages supported by GPS
will provide syntax highlighting in the editor.

@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
key manager dialog, @xref{The Key Manager Dialog}.

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

@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 type of information displayed depends on the current state of GPS.

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

In addition, the documentation for the entity is displayed. This is the block
of comments just before or just after the entity's declaration of body. There
mustn't be any blank line between the two. For instance, the following are
valid documentation for Ada and C:

@smallexample
--  A comment for A
A : Integer;

B : Integer;
--  A comment for B

C : Integer;

--  Not a comment for C, there is a blank linke
@end smallexample

In debugging mode, the value of the variable under the mouse is displayed in
the pop up window if the variable is known to the debugger.
Otherwise, the normal mode information is displayed.

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

@item Code completion
@cindex completion

GPS provides two kinds of code completion: a smart code completion based
on semantic information (see @ref{Smart Completion}), and a text 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 key manager dialog) after a partial
word: the next possible completion will be inserted in the editor. Typing this
key again will cycle through the list of possible completions.

Text completions are searched in all currently open source files, 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 line
You can configure the editor to highlight the current line with a certain
color. @xref{The Preferences Dialog}.

@item Current block highlighting
@cindex block
If this preference is enabled, the editor will highlight the current block
of code, e.g. the current @code{begin...end} block, or loop statement,
etc@dots{}

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

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

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

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

@c @item Automatic syntax checking
@c @cindex automatic syntax checking
@c When enabled, the editor will perform on-the-fly syntax checks, and will
@c underline the errors in your file as you type.

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

@item Automatic highlighting of entities
@cindex auto highlighting
When the cursor is positioned on an entity in the source editor, GPS will
highlight all references to this entity in the current editor.

When the cursor moves away from the entity, the highlighting is removed.

This is controlled by the plugin @code{auto_highlight_occurrences.py}: it can
be deactivated by deactivating the plugin (@pxref{The Plug-ins Editor}).

Details such as presence of indications in the Speed Column or highlighting
color can be customized in the @code{Plugins} section of
@ref{The Preferences Dialog}.

@end table

@cindex emacs
GPS also integrates with existing third party editors such as
@code{Emacs} or @code{vi}. @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.

In addition, there are several ways to define new key bindings, see
@ref{Defining text aliases} and @ref{Binding actions to keys}.

@table @key
@item Ctrl-Shift-u
@cindex hexadecimal
@cindex ASCII
Pressing these three keys and then holding Ctrl-Shift allow you to enter
characters using their hexadecimal
value. For example, pressing @key{Ctrl-Shift-u-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

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

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

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

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

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

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

@item Open From Host...
@anchor{Open From Host}
@cindex open
Open a file selector dialog where you can specify a remote host, as
defined in @ref{The remote configuration dialog}. You have access to a remote
host file system, can specify a file which can be edited in GPS. When you
hit the save button or menu, the file will be saved on the remote host.

See also @ref{Using GPS for Remote Development} for a more efficient
way to work locally on remote files.

@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 More
@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, so that if you reload the same project you get
back to the same situation you were in when you left GPS. Instead, if you load
a different project another desktop will be loaded (or the default desktop).
Through the preference "Save Desktop On Exit", you can also automatically save
this desktop when you quit GPS.

@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 @ref{The Locations View}.

@item Export Locations to editor
@cindex export locations
List the contents of the Locations view in a standard text editor.

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

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

By default, if you press Paste, the newest text will be copied at the current
position. But if you select Paste Previous immediately after (one or more times)
you can instead paste text that was copied previously in the clipboard.

For instance, if you copy through @code{Edit->Copy} the text "First", then
copy the text "Second", you can then select @code{Edit->Paste} to insert
"Second" at the current location. If you then select
@code{Edit->Paste Previous}, "Second" will be replaced by "First".

Selecting this menu several times will replace the text previously pasted
by the previous one in the list saved in the clipboard. When reaching the end
of this list, GPS will started from the beginning, and insert again the last
text copied into the clipboard.

The size of this list is controlled by the @code{Clipboard Size} preference.

For more information, @xref{The Clipboard View}.

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

@item Rectangles...
See the section @pxref{Rectangles} for more information on rectangles.

@item Insert File...
Open a file selection dialog and insert the contents of this file in
the current source editor, at the current cursor location.

@item Insert Shell Output...
Open an input window at the bottom of the GPS window where you can specify any
external command. The output of the command will be inserted at the current
editor location in case of success. If text is selected, the text is passed
to the external command and replaced by the command's output.

@item Format Selection
@cindex format selection
Indent and format the selection or the current line.
@xref{The Preferences Dialog}, for preferences related to source formatting.

@item Smart Completion
@anchor{Smart Completion}
@cindex completion

Complete the identifier prefix under the cursor, and list the results in a
pop-up list. This command can take advantage of an entity database and offers
completions from the entire project, along with documentation extracted from
comments surrounding declarations. To take full advantage of this feature, the
smart completion preference must be enabled, which will imply the computation
of the entity database at GPS startup.

In order to use this feature, open any Ada file, and begin to type an
identifier. It has to be an identifier declared either in the current file (and
accessible from the cursor location) or in one of the packages of the project
loaded. Move the cursor right after the last character of the incomplete
identifier and hit the completion key (which is @key{ctrl+space} by default).
GPS will open a popup displaying all the known identifiers beginning with the
prefix you typed. You can then browse among the various proposals by clicking
on the  @key{up} and @key{down} keys, or using the left scrollbar. For each
entity, a documentation box is filled. If the location of the entity is known,
it's displayed as an hyperlink, and you can jump directly to its declaration by
clicking on it.

Typing new letters will reduce the range of proposal, as long as there remain
solutions. Once you've selected the expected completion, you can validate by
pressing @key{Enter}.

Typing control characters (ie, characters which cannot be used in identifiers)
will also validate the current selection.

GPS is also able to complete automatically subprogram parameter or dotted
notations. For example, if you type

@smallexample
with Ada.
@end smallexample

the smart completion window will appear automatically, listing all the child
and nested packages of Ada. You can configure the time interval after which
the completion window appears (@pxref{The Preferences Dialog}).

You can also write the beginning of the package, e.g.:

@smallexample
with Ada.Text
@end smallexample

pressing the completion key will offer you Text_IO.

If you are in a code section, you will be able to complete the fields of
a record, or the contents of a package, e.g.:

@smallexample
   type R is record
      Field1 : Integer;
      Field2 : Integer;
   end record;

   V : R;

begin

   V.
@end smallexample

Completing V. will propose Field1 and Field2.

The smart completion can also give you the possible parameters of a call
you're currently making. For example, in the following code:

@smallexample

   procedure Proc (A, B, C : Integer);

begin

   Proc (1,
@end smallexample

If you hit the completion key after the comma, the smart completion engine
will propose you to complete with the named parameters "B =>", "C =>" or
directly to complete with all the remaining parameters, which in this case
will be "B =>, C => )".

@iftex
@cindex screen shot
@image{smart-completion, 15cm}
@end iftex

@ifhtml
@cindex screen shot
@image{smart-completion}
@end ifhtml

Limitations:

@table @bullet

@item This feature is currently only available for Ada.
Using the smart completion on non Ada files behaves as the identifier completion does.
@xref{Complete Identifier}.

@end table

@item More Completion
@cindex completion

This submenu contains more ways to automatically complete code

@table @bullet
@item Expand Alias
Consider the current word as an alias and expand according to aliases
defined in @ref{Defining text aliases}.

@item Complete Identifier
@anchor{Complete Identifier}
@cindex complete identifier
Complete the identifier prefix under the cursor. This command will cycle
through all identifiers starting with the given prefix.

@item Complete Block
@cindex complete block
Close the current statement (if, case, loop) or unit (procedure,
function, package). This action works only on an Ada buffer.

@end table

@item Selection
@cindex selection

@table @bullet

@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 Refill
@cindex refill
Refill text on the selection or current line according to the right
margin as defined by the right margin preference
(@pxref{The Preferences Dialog}).

@item Refill with fmt
@cindex refill
@cindex fmt
Refill text on the selection or current line using the external utility
@code{fmt}. If @code{fmt} is not found on your system, this menu will not be
displayed.

@item Sort
Sort the selected lines alphabetically. This is particularly useful when
editing non source code, or for specific parts of the code, like with clauses
in Ada.

@item Sort Reverse
Sort the selected lines in reverse alphabetical order

@item Pipe in external program...
Open an input window at the bottom of the GPS window where you can specify any
external command, which will take the current selection as input. The output of
the command will replace the contents of the selection on success.

@item Serialize
Increment a set of numbers found on adjacent lines.
The exact behavior depends on whether there is a current selection or not.

If there is no selection, then the set of lines considered is from
the current line on and includes all adjacent lines that have at
least one digit in the original columns. In the following example,
'|' marks the place where the cursor is at the beginning:

@smallexample
  AAA |10 AAA
  CCC 34567 CCC
  DDD DDD
@end smallexample

then only the first two lines will be modified, and will become

@smallexample
  AAA 10 AAA
  CCC 11 CCC
  DDD DDD
@end smallexample

If there is a selection, all the lines in the selection are
modified. For each line, the columns that had digits in the first
line are modified, no matter what they actually contain. In the
example above, if you select all three lines, the replacement becomes

@smallexample
  AAA 10 AAA
  CCC 11567 CCC
  DDD 12D
@end smallexample

ie only the fifth and sixth columns are modified since only those
columns contained digits in the first line. This feature assumes that
you are selecting a relevant set of lines. But it allows you to
transform blank lines more easily. For instance, if you have

@smallexample
  AAA 1
  BBB
  CCC
@end smallexample

this is transformed into

@smallexample
  AAA 1
  BBB 2
  CCC 3
@end smallexample

@item Untabify
Replace all tabs in the current selection (or in the whole buffer if
there is no selection) by the appropriate number of spaces

@item Move Right
@itemx Move Left
Shift the currently selected lines (or the current line if there is no
selection) one character to the right or to the left

@end table

@item Fold all blocks
@cindex fold
Collapse all the blocks in the current file.

@item Unfold all blocks
@cindex unfold
Uncollapse all the blocks in the current file.

@item Create Bookmark
Creates a new Bookmark at cursor position. For more information,
@xref{Bookmarks}.

@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 Generate Body
@cindex gnatstub
@cindex generate body
Generate Ada body stub for the current source editor by calling the
external tool @code{gnatstub}.

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

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

@end table

@item Edit with external editor
@xref{Using an External Editor}.

@item Aliases
@cindex alias
Display the Aliases editor. @xref{Defining text aliases}.

@item Key shortcuts
@cindex key shortcuts
Give access to the key manager dialog, to associate commands with special
keys. @xref{The Key Manager Dialog}.

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

@end table

@c --------------------------------------------------------------------
@node Rectangles
@section Rectangles
@cindex rectangle
@c -------------------------------------------------------------------

@noindent
Rectangle commands operate on a rectangular area of the text, that is
all the characters between two columns in a certain range of lines.

A rectangle is selected using the standard selection mechanism. You can
therefore use either the mouse to highlight the proper region, or
@key{shift} and the cursor keys to extend the selection, or the Emacs
selection (with the mark and the current cursor location) if you have
activated the @file{emacs.py} plugin.

Visually, a selected rectangle is exactly the same as the standard
selection. In particular, the characters after the last column, on each
line, will also be highlighted. The way the selection is interpreted (either
as a full text or as a rectangle) depends on the command you then chose to
manipulate the selection.

If you chose one of the commands from the @code{/Edit/Rectangles} menu,
the actual rectangle will extend from the top-left corner down to the
bottom-right corner. All characters to the right of the right-most column,
although they are highlighted, are not part of the rectangle.

Consider for instance the following initial text:

@smallexample
package A is
   procedure P;

   procedure Q;
end A;
@end smallexample

and assume we have selected from the character "p" in "procedure P", down
to the character "c" in "procedure Q".

The following commands can then be used (either from the menu, or you
can assign key shortcuts to them via the usual @code{/Edit/Key shortcuts}
menu.

@itemize @bullet

@item @code{Cut} or @code{Delete}
These commands will remove the selected text (and have no effect on empty
lines within the rectangle). The former will in addition copy the rectangle
to the clipboard, so that you can paste it later. In our example, we end up
with

@smallexample
package A is
   edure P;

   edure Q;
end A;
@end smallexample

@item @code{Copy}
This command has no visual effect, but copies the contents of the rectangle
into the clipboard.

@item @code{Paste}
Pastes the contents of the clipboard as a rectangle: each line from the
clipboard is treated independently, and inserted on successive lines in the
current editor. They all start in the same column (the one where the cursor
is initially in), and existing text in the editor lines is shifted to the
right). If for instance you now place the cursor in the second line, first
column, and paste, we end up with:

@smallexample
package A is
proc   edure P;

proc   edure Q;
end A;
@end smallexample

@item @code{Clear}
Replaces the contents of the selected rectangle with spaces. If we start
from our initial exmaple, we end up with the following. Note the difference
with @code{Delete}.

@smallexample
package A is
       edure P;

       edure Q;
end A;
@end smallexample

@item @code{Open}
Replaces the contents of the selected rectangle with spaces, but shifts the
lines to the right to do so. Note the difference with @code{Clear}.

@smallexample
package A is
       procedure P;

       procedure Q;
end A;
@end smallexample

@item @code{Replace With Text}
This is similar to @code{Clear}, but the rectangle is replaced with
user-defined text. The lines will be shifted left or right if the text you
insert is shorter (resp. longer) than the width of the rectangle. If for
instance we replace our initial rectangle with the text TMP, we end up with
the following. Note that the character "c" has disappeared, since TMP is
shorter than our rectangle width (4 characters). This command will impact
lines that are empty in the initial rectangle.

@smallexample
package A is
   TMPedure P;
   TMP
   TMPedure Q;
end A;
@end smallexample

@item @code{Insert Text}
This inserts a text to the left of the rectangle on each line. The following
example inserts TMP. Note the difference with @code{Replace With Text}. This
command will also insert the text on lines that are empty in the initial
rectangle.

@smallexample
package A is
   TMPprocedure P;
   TMP
   TMPprocedure Q;
end A;
@end smallexample

@end itemize

@c --------------------------------------------------------------------
@node Recording and replaying macros
@section Recording and replaying macros
@cindex macros
@c --------------------------------------------------------------------

@noindent
It is often convenient to be able to repeat a given key sequence a
number of times.

GPS supports this with several different methods:

@itemize @bullet
@item Repeat the next action

If there is a single key press that you wish to repeat a number of
times, you should first use the GPS action @code{"Repeat Next"} (bound
by default to @key{control-u}, but this can be changed as usual through
the @code{/Edit/Key Shortcuts} menu), then entering the number of times
you wish to repeat, and finally pressing the key you want.

For instance, the following sequence @key{control-u 79 -} will insert
79 characters '-' in the current editor. This proves often useful to
insert separators.

If you are using the emacs mode (see @code{/Tools/Plug-ins} menu),
you can also use the sequence @key{control-u 30 control-k} to delete
30 lines.

@item Recording macros

If you wish to repeat a sequence of more than 1 key, you should record
this sequence as a macro. All macro-related menus are found in
@code{/Tools/Macros}, although it is often more convenient to use these
through key bindings, which you can of course override.

You must indicate to GPS that it should start recording the keys you are
pressing. This is done through the @code{/Tools/Macros/Start Keyboard Macro}
menu. As its name indicates, this only records keyboard events, not mouse
events. Until you select @code{/Tools/Macros/Stop Macro}, GPS will keep
recording the events.

In Emacs mode, the macro actions are bound to @key{control-x (},
@key{control-x )} and @key{control-x e} key shortcuts. For instance,
you can execute the following to create a very simple macro that deletes the
current line, wherever your cursor initially is on that line:

@smallexample
@key{control-x (}     # start recording
@key{control-a}       # go to beginning of line
@key{control-k}       # delete line
@key{control-x )}     # stop recording
@end smallexample

@end itemize

@c --------------------------------------------------------------------
@node Contextual Menus for Editing Files
@section Contextual Menus for Editing Files
@cindex case exceptions
@c --------------------------------------------------------------------

Whenever you ask for a contextual menu (using e.g. the third button
on your mouse) on a source file, you will get access to a number of
entries, displayed or not depending on the current context.

Menu entries include the following categories:

@table @b

@item Source Navigation
@xref{Contextual Menus for Source Navigation}.

@item Dependencies
@xref{Dependency Browser}.

@item Entity browsing
@xref{Entity Browser}.

@item Project view
@xref{The Project View}.

@item Version control
@xref{The Version Control Contextual Menu}.

@item Debugger
@xref{Using the Source Editor when Debugging}.

@item Case exceptions
@xref{Handling of case exceptions}.

@item Refactoring
@xref{Refactoring}.

@end table

@cindex language, editor
@cindex character set
In addition, an entry @code{Properties...} is always visible in this
contextual menu. When you select it, a dialog pops up that allows you
to override the language used for the file, or the character set.

This can be used for instance if you want to open a file that does not
belong to the current project, but where you want to benefit from the
syntax highlighting that GPS knows how to.

It is not recommended to override the language for source files that
belong to the project. Instead, you should use the @code{Project Properties}
dialog and change the naming scheme if appropriate. This will ensure better
consistency between GPS and the compiler in the way they manipulate the
file.

@c -----------------------------------------------------------------
@node Handling of case exceptions
@section Handling of case exceptions
@cindex casing
@c -----------------------------------------------------------------

GPS keeps a set of case exceptions that is used by all
case insensitive languages. When editing or reformatting a buffer for
such a language the case exception dictionary will be checked
first. If an exception is found for this word or a substring of the
word, it will be used; otherwise the specified casing for keywords or
identifiers is used. A substring is defined as a part of the word
separated by underscores.

Note that this feature is not activated for entities (keywords or
identifiers) for which the casing is set to @code{Unchanged}. See
@pxref{The Preferences Dialog}.

A contextual menu named @b{Casing} has the following entries:

@table @b
@item Lower @i{entity}
Set the selected entity in lower case.

@item Upper @i{entity}
Set the selected entity in upper case.

@item Mixed @i{entity}
Set the selected entity in mixed case (set the first letter and
letters before an underscore in upper case, all other letters are set
to lower case).

@item Smart Mixed @i{entity}
Set the selected entity in smart mixed case. Idem as above except that
upper case letters are kept unchanged.

@item Add exception for @i{entity}
Add the current entity into the case exception dictionary.

@item Remove exception for @i{entity}
Remove the current entity from the case exception dictionary.
@end table

To add or remove a substring exception into/from the dictionary you need to
first select the substring on the editor. In this case the last two
contextual menu entries will be:

@table @b
@item Add substring exception for @i{str}
Add the selected substring into the case substring exception dictionary.

@item Remove substring exception for @i{str}
Remove the selected substring from the case substring exception dictionary.
@end table

@c --------------------------------------------------------------------------
@node Refactoring
@section Refactoring
@cindex refactoring
@c --------------------------------------------------------------------------

@noindent
GPS includes basic facilities for refactoring your code. Refactoring is the
standard term used to describe manipulation of the source code that do not
affect the behavior of the application, but help reorganize the source code
to make it more readable, more extendable, @dots{}

Refactoring technics are generally things that programmers are used to do by
hand, but which are faster and more secure to do automatically through a tool.

One of the basic recommendations when you refactor your code is to recompile
and test your application very regularly, to make sure that each of the small
modifications you made to it didn't break the behavior of your application.
This is particularly true with GPS, since it relies on the cross-references
information that is generated by the compiler. If some of the source files
have not been recompiled recently, GPS will print warning messages indicating
that the renaming operation might be dangerous and/or only partial.

One of the reference books that was used in the choice of refactoring methods
to implement is "Refactoring", by Martin Fowler (Addison Wesley).

@menu
* Rename Entity::
* Name Parameters::
* Extract Subprogram::
@end menu

@c --------------------------------------------------------
@node Rename Entity
@subsection Rename Entity
@c --------------------------------------------------------

@noindent
Clicking on an entity in a source file and selecting the
@code{Refactoring/Rename} menu will open a dialog asking for the new name
of the entity. GPS will rename all instances of the entity in your application.
This includes the definition of the entity, its body, all calls to it, etc@dots{}
Of course, no comment is updated, and you should probably check manually that
the comment for the entity still applies.

GPS will handle primitive operations by also renaming the operations it
overrides or that overrides it. This means that any dispatching call to that
operation will also be renamed, and the application should still work as
before. If you are renaming a parameter to a subprogram, GPS can also rename
parameters with similar names in overriding or overridden subprograms.

The behavior when handling read-only files can be specified: by default,
GPS will not do any refactoring in these files, and will display a dialog
listing all of them; but you can also choose to make them writable just
as if you had clicked on the "Read-Only" button in the status bar of the
editor and then have GPS perform the renaming in them as well.

@c --------------------------------------------------------
@node Name Parameters
@subsection Name Parameters
@c --------------------------------------------------------

@noindent
If you are editing Ada code and click on a call to a subprogram, GPS will
display a contextual menu @code{Refactoring/Name parameters}, which will
replace all unnamed parameters by named parameters, as in:

@smallexample
   Call (1, 2)
=>
   Call (Param1 => 1, Param2 => 2);
@end smallexample

@c ----------------------------------------------------------
@node Extract Subprogram
@subsection Extract Subprogram
@c ----------------------------------------------------------

This refactoring is used to move some code from one place to a separate
subprogram. The goal is to simplify the original subprogram, by moving part of
its code elsewhere.

Here is an example from the "Refactoring" book. The refactoring will take
place in the body of the package @file{pkg.adb}, but the spec is needed so that
you can compile the source code (a preliminary step mandatory before you can
refactor the code).

@smallexample
@b{pragma} Ada_05;

@b{with} Ada.Containers.Indefinite_Doubly_Linked_Lists;
@b{with} Ada.Strings.Unbounded;

@b{package} Pkg @b{is}

   @b{type} Order @b{is tagged null record};
   @b{function} Get_Amount (Self : Order) @b{return} Integer;

   @b{package} Order_Lists@b{is new}
      Ada.Containers.Indefinite_Doubly_Linked_Lists (Order);

   @b{type} Invoice @b{is tagged record}
      Orders : Order_Lists.List;
      Name   : Ada.Strings.Unbounded.Unbounded_String;
   @b{end record};

   procedure Print_Owing (Self : Invoice);

@b{end} Pkg;
@end smallexample

The initial implementation for this code is given by the following code:

@smallexample
@b{pragma} Ada_05;
@b{with} Ada.Strings.Unbounded;  @b{use} Ada.Strings.Unbounded;
@b{with} Ada.Text_IO;            @b{use} Ada.Text_IO;

@b{package} body Pkg @b{is}
   @b{use} Order_Lists;

   @i{----------------}
   @i{-- Get_Amount --}
   @i{----------------}

   @b{function} Get_Amount (Self : Order) @b{return} Integer @b{is}
   @b{begin}
      @b{return} 0;
   @b{end} Get_Amount;

   @i{-----------------}
   @i{-- Print_Owing --}
   @i{-----------------}

   @b{procedure} Print_Owing (Self : Invoice) @b{is}
      E : Order_Lists.Cursor := First (Self.Orders);
      Outstanding : Natural := 0;
      Each : Order;
   @b{begin}
      @i{--  <<< line 30}
      @i{--  Print Banner}

      Put_Line ("********************************");
      Put_Line ("***** Customer Owes         ****");
      Put_Line ("********************************");  @i{--  << line 35}

      @i{--  Calculate Outstanding}

      @b{while} Has_Element (E) @b{loop}
         Each := Element (E);
         Outstanding := Outstanding + Each.Get_Amount;
         Next (E);
      @b{end loop};

      @i{--  Print Details}

      Put_Line ("Name: " & To_String (Self.Name));
      Put_Line ("Outstanding:" & Outstanding'Img);
   @b{end} Print_Owing;
@b{end Pkg};
@end smallexample

The procedure @code{Print_Owing} is too long and does several independent
actions. We will perform a series of three successive refactoring steps to
extract the code and move it elsewhere.

The first is the code that prints the banner. Moving it is easy, since this
code does not depend on any context. We could just do a copy-paste, but then
we would have to create the new subprogram. Instead, we select lines 30 to
35, and then select the contextual menu @code{Refactoring/Extract Subprogram}.
GPS will then automatically change @code{Print_Owing} and create a new
procedure @code{Print_Banner} (the name is specified by the user, GPS does
not try to guess it). Also, since the chunk of code that is extracted starts
with a comment, GPS automatically uses that comment as the documentation for
the new subprogram. Here is part of the resulting file:

@smallexample
@b{package body} Pkg @b{is}

   @b{procedure} Print_Banner;
   @i{--  Print Banner}

   @i{------------------}
   @i{-- Print_Banner --}
   @i{------------------}

   @b{procedure} Print_Banner @b{is}
   @b{begin}
      Put_Line ("********************************");
      Put_Line ("***** Customer Owes         ****");
      Put_Line ("********************************");
   @b{end} Print_Banner;

   ... (code not shown)

   @b{procedure} Print_Owing (Self : Invoice) @b{is}
      E : Order_Lists.Cursor := First (Self.Orders);
      Outstanding : Natural := 0;
      Each : Order;
   @b{begin}
      Print_Banner;

      @i{--  Calculate Outstanding}

      @b{while} Has_Element (E) @b{loop}
         Each := Element (E);
         Outstanding := Outstanding + Each.Get_Amount;
         Next (E);
      @b{end loop};

      @i{--  Print Details   <<< line  54}

      Put_Line ("Name: " & To_String (Self.Name));
      Put_Line ("Outstanding:" & Outstanding'Img);  @i{--  line 57}
   @b{end} Print_Owing;

@b{end} Pkg;
@end smallexample

A more interesting example is when we want to extract the code to print
the details of the invoice. This code depends on one local variable and
the parameter to Print_Owing. When we select lines 54 to 57 and extract
it into a new @code{Print_Details} subprogram, we get the following
result. GPS automatically decides which variables to extract, and whether
they should become parameters of the new subprogram, or local variables. In
the former case, it will also automatically decide whether to create
@code{"in"}, @code{"out"} or @code{"in out"} parameters. If there is
a single @code{"out"} parameter, it will automatically create a function
rather than a procedure.

GPS will use, for the parameters, the same name that was used for the local
variable. Very often, it will make sense to recompile the new version of the
source, and then apply the @code{Rename Entity} refactoring to have more
specific names for the parameters, or the @code{Name Parameters} refactoring
so that the call to the new method uses named parameters to further clarify
the code.

@smallexample
   ... code not shown

   @b{procedure} Print_Details
     (Self : Invoice'@b{Class};
      Outstanding : Natural);
   @i{--  Print Details}

   @i{-------------------}
   @i{-- Print_Details --}
   @i{-------------------}

   @b{procedure} Print_Details
     (Self : Invoice'@b{Class};
      Outstanding : Natural)
   @b{is}
   @b{begin}
      Put_Line ("Name: " & To_String (Self.Name));
      Put_Line ("Outstanding:" & Outstanding'Img);
   @b{end} Print_Details;

   @b{procedure} Print_Owing (Self : Invoice) @b{is}
      E : Order_Lists.Cursor := First (Self.Orders);
      Outstanding : Natural := 0;
      Each : Order;
   @b{begin}
      Print_Banner;

      @i{--  Calculate Outstanding}

      @b{while} Has_Element (E) @b{loop}
         Each := Element (E);
         Outstanding := Outstanding + Each.Get_Amount;
         Next (E);
      @b{end loop};

      Print_Details (Self, Outstanding);
   @b{end} Print_Owing;
@end smallexample

Finally, we want to extract the code that computes the outstanding
amount. When this code is moved, the variables @code{E} and @code{Each}
become useless in @code{Print_Owing} and are moved into the new
subprogram (which we will call @code{Get_Outstanding}. Here is the result
of that last refactoring (the initial selection should include the blank
lines before and after the code, to keep the resulting @code{Print_Owing}
simpler). GPS will automatically ignore those blank lines.

@smallexample
   ... code not shown

   @b{procedure} Get_Outstanding (Outstanding : @b{in out} Natural);
   @i{--  Calculate Outstanding}

   @i{---------------------}
   @i{-- Get_Outstanding --}
   @i{---------------------}

   @b{procedure} Get_Outstanding (Outstanding : @b{in out} Natural) @b{is}
      E : Order_Lists.Cursor := First (Self.Orders);
      Each : Order;
   @b{begin}
      @b{while} Has_Element (E) @b{loop}
         Each := Element (E);
         Outstanding := Outstanding + Each.Get_Amount;
         Next (E);
      @b{end loop};
   @b{end} Get_Outstanding;

   @b{procedure} Print_Owing (Self : Invoice) @b{is}
      Outstanding : Natural := 0;
   @b{begin}
      Print_Banner;
      Get_Outstanding (Outstanding);
      Print_Details (Self, Outstanding);
   @b{end} Print_Owing;
@end smallexample

Note that the final version of @code{Print_Owing} is not perfect. For
instance, passing the initial value 0 to @code{Get_Outstanding} is
useless, and in fact that should probably be a function with no
parameter. But GPS already saves a lot of time and manipulation.

Finally, a word of caution: this refactoring does not check that you are
giving a valid input. For instance, if the text you select includes a
@code{declare} block, you should always include the full block, not just
a part of it (or select text between @code{begin} and @code{end}). Likewise,
GPS does not expect you to select any part of the variable declarations,
just the code.

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

@noindent
GPS is 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 gnuserv url
See @url{http://www.hpl.hp.com/personal/ange/gnuserv/home.html} 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 @code{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 be found in the PATH,
and thus is not supported on Windows systems. Under Windows systems,
you can use the @code{custom} editor instead.

@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://standards.freedesktop.org/clipboards-spec/clipboards-latest.txt} for more
information.

@c --------------------------------------------------------------------------
@node Saving Files
@section Saving Files
@cindex saving
@c --------------------------------------------------------------------------

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

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

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

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

@iftex
@cindex screen shot
@image{save-dialog, 7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{save-dialog}
@end ifhtml

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

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

@c --------------------------------------------------------------------
@node Remote Files
@section Remote Files
@cindex remote files
@cindex ftp
@cindex ssh
@cindex rsh
@cindex rsync
@cindex telnet
@cindex http
@c --------------------------------------------------------------------

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

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

@smallexample
Editor.edit protocol://user@@machine/full/path
@end smallexample

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

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

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

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

The following protocols are supported:

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

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

The remote system must be a Unix-like system with support for standard Unix
commands like @code{test}, @code{echo}, @code{rm} and @code{ls}.

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

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

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

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

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

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

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

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

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

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

If you set up the environment variable RSYNC_RSH to ssh before starting gps,
the connection will then be encrypted when transferring the files, and the
connection will be performed using ssh instead of rsh.

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

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

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

@item http
This is the usual http protocol to download documents from the web. It is in
particular useful for documentation

@end table

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

@menu
* Support for Cross-References::
* The Navigate Menu::
* Contextual Menus for Source Navigation::
* Navigating with hyperlinks::
* Highlighting dispatching calls::
@end menu

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

@noindent
GPS provides cross-reference navigation for program entities, such as
types, procedures, functions, variables, @dots{}, defined in your
application. The cross-reference support in GPS relies on the compiler
generated xref information, which means that you need to either compile
your project first before being able to navigate, or use the menu
@code{Build->Recompute Xref info}.
Similarly when your sources have been modified, you need to rebuild and
recompute xref information so that your changes are taken into account.

Here are language specific information about source navigation:

@table @b
@item Ada
@cindex Ada
@cindex GNAT
The GNAT compiler is used to generate the cross-references information
needed by GPS by default, unless you are using the @code{-gnatD} or
@code{-gnatx} switches, in whcih case no cross reference information
will be available.

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

@cindex ALI
There are a few special cases where GPS cannot 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 cannot 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 project view
(left-side panel on the main window), and selecting the menu "Parse
all xref information".

@item C/C++
@cindex C
@cindex C++
The GCC C and C++ compilers that come with GNAT need to be used to generate
the cross-references information needed by GPS, via the @code{-fdump-xref}
switch. This means that you need to first add the @code{-fdump-xref}
switch to your project's switches for C and C++ sources, and compile
your application before you browse through the cross-references or view
various graphs in GPS.
If sources have been modified, you should recompile the modified files.

@end table

@subsection Loading xref info in memory
@cindex Load xref info in memory

The cross-reference information, as mentioned above, is generated either
by the compiler when you recompile your sources, or explicitly when you
select the menu @code{Build->Recompute Xref info}.

This information will be loaded in memory automatically by GPS when it
needs it, and as little as possible, to limit the memory footprint. However,
this means that some operations, for instance searching for all the references
to a global entity, will need to parse most, if not all, of the cross-reference
information. This will slow done the search the first time (and then the
information is in memory and the search is fast, unless the cross-reference
information has been regenerated on the disk).

You can select the menu @code{Build->Load xref info in memory} to force GPS to
load all the available information immediately in memory. This will speed up
future queries.

Note that GPS always loads all xref information for C and C++ sources in
order to provide accurate source navigation, so this menu is mainly relevant
for Ada sources.

A preference can be set to have GPS load the cross-information automatically
on startup, @xref{The Preferences Dialog}.
@c ??? need to xref to specific pref, this xref is too general

@subsection Ada xrefs heuristics
@cindex Ada xrefs heuristics

GPS is able to provide some basic navigation support for Ada sources in the
absence of information coming from the compiler. It uses a built-in Ada parser
parsing the Ada files at startup and allowing navigation in simple cases.

In this mode, GPS is able to navigate to an entity body from the declaration,
and to an entity declaration from the body. In case of other references, GPS
will navigate to the declaration on simple cases, namely if the heuristics
provide an information without ambiguity. In particular, it may not work
with overloaded entities.

These heuristics are not used in global reference searching operations or call
graphs.

Note that this parser is also used to provide the Ada outline view, code
completion and entity view.

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

@noindent

@table @b
@item Find or 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 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 View}.

@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 the availability of cross-reference information.
@xref{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 the availability of cross-reference information.
@xref{Support for Cross-References}.

@item Goto Matching Delimiter
@cindex goto matching delimiter
Go to the delimiter matching the one right before (for a closing delimiter) or
right after (for an opening delimiter) the cursor if any.

@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 Entity...
@cindex goto entity
Open a dialog allowing browsing of the entities loaded in the project.
This dialog functions similarly to @ref{The Entity View}.

@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

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

@item Start Of Statement
@cindex Start Of Statement
Move the cursor position to the start of the current statement, move
to the start of the enclosing statement if the cursor position is
already at the start of the statement.

@item End Of Statement
@cindex End Of Statement
Move the current cursor position to the end of the statement, move
to the end of the enclosing statement if the cursor position is
already at the end of the statement.

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

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

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

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

@item Back
@cindex Back
Go to previous location.

@item Forward
@cindex Forward
Go to next location.

@end table

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

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

@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 full declaration of @i{entity}
@cindex goto declaration
This contextual menu appears for a private or limited private types. Go
to the full 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 type declaration of @i{entity}
@cindex goto type declaration
Go to the type declaration 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 Display type hierarchy for @i{entity}
@cindex display type hierarchy
This contextual menu appears for derived or access types. Output the
type hierarchy for @i{entity} into the location view. 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 declarations of @i{entity}
@cindex goto declaration
This contextual menu appears when you are clicking on a subprogram call that
is a dispatching call. In such a case, there is no possibility for GPS to
know what subprogram will actually be called at run time, since that depends
on dynamic information. It therefore gives you a list of all entities in the
tagged type hierarchy, and lets you choose which of the declarations you want
to jump to. See also the @file{methods.py} plug-in (enabled by default) which,
given an object, lists all its primitive operations in a contextual menu so
that you can easily jump to them. See also the contextual menu
@file{References/Find References To...} which allows you to find all calls
to a subprogram or to one of its overriding subprograms.

@item Goto bodies of @i{entity}
@cindex goto body
This is similar to @i{Goto declarations of}, but applies to the bodies of
the entities.

@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 @i{Entity} calls
Display a list of all subprograms called by @i{entity} in a tree
view. This is generally more convenient than using the corresponding
Browsers/ submenu if you expect lots of references, @xref{The Callgraph View}.

@item @i{Entity} is called by
Display a list of all subprograms calling @i{entity} in a tree
view. This is generally more convenient than using the correponding
Browsers/ submenu if you expect lots of references, @xref{The Callgraph View}.

@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 Find all references to @i{entity}
@cindex find all references
Find all references to @i{entity} in all the files in the project, @xref{Find All References}.

@item Find all references...
This menu is similar to the one above, except it is possible to select more
precisely what kind of reference should be selected. It is also possible
to indicate the scope of the search, and whether the context (or caller)
at each reference should be displayed. Computing the caller information will
take slightly longer though.

@cindex primitive operation
This dialog has an option @code{Include overriding and overriden operations},
which, when activated, will include references to overriden or overriding
entities of the one you selected.

This is particularly useful when you are wondering whether you can easily
modify the profile of a primitive operation, since you can then see what
other entities will also be impacted. If you select only the @code{declaration}
check box, you will see the list of all related primitive operations.

@cindex imported entities
This dialog also allows you to find out which entities are imported from
a given file/unit. Click on any entity from that file (for instance on the
@code{with} line for Ada code), then select the @code{All entities imported
from same file} toggle button. This will display in the location window the
list of all entities imported from the same file as the entity selected.

In addition, if you have selected the @code{Show context} option, you will
get a list of all the exact references to these entities within the file.
Otherwise, you just get a pointer to the declaration of the imported
entities.

@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 Variables used in @i{entity}
@cindex variables used
Find all variables (local or global) used in @i{entity} and list each first
reference in the locations window.

@item Non Local variables used in @i{entity}
Find all non-local variables used in the entity.
@end table

@item Methods of @i{entity}
@cindex methods
@cindex primitive operations
This submenu is only visible if you have activated the plug-in
@file{methods.py} (which is the case by default), and when you click on
a tagged type or an instance of a tagged type. This menu lists all the
primitive operations of that type, and you can therefore easily jump to
the declaration of any of these operations.

@item Browsers
@cindex browsers
This item gives access to graph representations of callers and callees for
subprograms.

@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 subprograms called by @i{entity}. @xref{Call Graph}.

@item @i{Entity} calls (recursively)
@cindex call graph
@cindex calls
Open or raise the call graph browser on the specified entity and display all
the subprograms called by @i{entity}, transitively for all subprograms.
Since this can take a long time to compute and generate a very large graph,
an intermediate dialog is displayed to limit the number of subprograms to
display (1000 by default). @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 subprograms 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.
@end table

@item Expanded code
Present for Ada files only. This menu generates a .dg file using your gnat
compiler (using the -gnatGL switch) and displays the expanded code. This can be
useful when investigating low-level issues and tracing precisely how the source
code is transformed by the GNAT front-end.

@table @command
@item Show subprogram
Display expanded code for the current subprogram in the current editor.

@item Show file
Display expanded code for the current file in the current editor.

@item Show in separate editor
Display expanded code for the current file in a new editor.

@item Clear
Remove expanded code from the current editor.
@end table

For Ada files only, this entry will generate, and will open this file
at the location corresponding to the current source line.

@item Open <filename>
When you click on a filename (for instance a C' @code{#include}, or an error
message in a log file), this menu gives you a way to open the corresponding
file. If the file name was followed by ":" and a line number, the
corresponding line is activated.

@end table

@c --------------------------------------------------------------------
@node Navigating with hyperlinks
@section Navigating with hyperlinks
@cindex hyperlinks
@c --------------------------------------------------------------------

When the Control key is pressed and you start moving the mouse, entities in
the editors under the mouse cursor become hyperlinks and the mouse cursor
aspect changes.

Left-clicking on a reference to an entity will open a source editor on the
declaration of this entity, and left-clicking on an entity declaration will
open an editor on the implementation of this entity.

Clicking with the middle button on either a reference to an entity or the
declaration of an entity will jump directly to the implementation or type
completion) of this entity.

Note that for efficiency, GPS may create hyperlinks for some entities which
have no associated cross reference. In this case, clicking will have no
effect, even though an hyperlink may have been displayed.

This behavior is controlled by the @code{Hyper links} preference.

@c --------------------------------------------------------------------
@node Highlighting dispatching calls
@section Highlighting dispatching calls
@cindex dispatching
@c --------------------------------------------------------------------

@noindent
Dispatching calls in Ada and C++ source code are highlighted by default
in GPS via the @code{dispatching.py} plug-in.

Based on the cross-reference information, this plug-in will highlight
(with a special color that you can configure in the preferences dialog)
all calls that are dispatching (or calls to virtual methods in C++).
A dispatching call, in Ada, is a subprogram call where the actual
subprogram that is called is not known until run time, and is chosen
based on the tag of the object (so this of course only exists when you
are using object-oriented programming).

To disable this highlighting (which might sometimes be slow if you are
using big sources, even though the highlighting itself is done in the
background), you can go to the @code{/Tools/Plug-ins} menu, and
disable the @code{dispatching.py} plug-in.

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

@noindent
@cindex project view
The section on the project view (@ref{The Project View}) 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::
* Supported Languages::
* Scenarios and Configuration Variables::
* Extending Projects::
* Project View::
* Disabling Project Edition Features::
* The Project Menu::
* The Project Wizard::
* The Project Dependencies Editor::
* 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. 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.

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 recommended reading if you want to use
some of the more advanced capabilities of project files which are not
yet supported by the graphical interface.

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

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

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

@cindex GNAT
All command-line GNAT tools are project aware, meaning that the notion
of project goes well beyond GPS' user interface. Most capabilities
of project files can be accessed without using GPS itself, making
project files very attractive.

@cindex ADA_PROJECT_PATH
GPS uses the same mechanisms to locate project files as GNAT
itself:

@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.
@item predefined project path.
The compiler itself defines a predefined project path, in which standard
libraries can be installed, like XML/Ada for instance.
@end itemize

@subsection Contents of project files
@cindex project file

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

@cindex project comments
A project file can contain comments, which have the same format as in Ada,
that is they start by "--" and extend to the end of the line.
You can add comments when you edit the project file manually. GPS will
attempt to preserve them when you save the project through the menu, but this
will not always be possible. It helps if the comments are put at the end of
the line, as in

@smallexample
project Default is
    for Source_Dirs use ();  --  No source in this project
end Default;
@end smallexample

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

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

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

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

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

@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 refers to the way files are named for each
   languages of the project. This is used by GPS to choose the language
   support to use when a source file is opened. This is also used to
   know what tools should be used to compile or otherwise work with a
   source file.

@item @b{Embedded targets and cross environments}:
@cindex cross environment
   GPS supports cross environment software development: GPS itself can
   run on a given host, such as GNU/Linux, while compilations, runs and
   debugging occur on a different remote host, such as Sun/Solaris.

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

@end itemize

@c -------------------------------------------------------------------
@node Supported Languages
@section Supported Languages
@cindex languages
@cindex text files
@c -------------------------------------------------------------------

@noindent
Another information stored in the project is the list of languages that
this project knows about. GPS support any number of language, with any name
you choose. However, advanced support is only provided by default for some
languages (Ada, C and C++), and you can specify other properties of the
languages through customization files
(@pxref{Adding support for new languages}).

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

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

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

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

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

By default, GPS provides support for a number of languages. In most cases,
this support takes the form of syntax highlighting in the editor, and possibly
the Outline View. Other languages have advanced cross-references available.

All the supported languages can be added to the project, but you can also add
your own languages as you need (either by editing the project files by hand,
or by creating XML files to add GPS support for these languages, which will
then show in the project properties editor graphically).

@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 host computer environment, or directly set in
GPS. The interface to manipulate these scenarios is the scenario view, which
can be displayed by selecting the menu @code{Tools->Views->Scenario}.
It can be convenient to drag this window with your mouse, and drop it above
the project view, so that you can see both at the same time.

This area allows you to select new values for the scenario variables defined
in your project, and thus change dynamically the view GPS has of your project
and your source files.

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

There is one limitation in what GPS can do with scenario variables: although
gnatmake and gprbuild have no problem dealing with scenario variables
whose default value is not a static string (for instance a concatenation, or
the value of another scenario variable), GPS will not be able to edit such
a project graphically. Such projects will load fine in GPS though.

@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 View or the Scenario View itself. Select the
menu @code{Project->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 scenario view
@cindex scenario view

@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 host computer environment, although
you can of course change its value later on inside GPS. Note that
selecting a new value for the scenario variable does not change the
actual value of the environment variable, which is only used to get the
default initial value of the scenario variable.

When you spawn external tools like gnatmake for instance, you can
also specify the value they will use for the scenario variable by
using a command line switch, typically @code{-X}.

@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 by right-clicking on the name
of the variable, and selecting one of @code{Edit properties} or
@code{Delete variable}.

@subsection Editing existing configuration variables
@cindex editing configuration variable

@noindent
If at least one configuration variable is defined in your project, the
scenario view will contain something similar to:

@iftex
@cindex screen shot
@image{explorer-scenario, 5.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.

As soon as a new value is selected, GPS will recompute the project
view (in case source directories, object directories or list
of source files have changed). A number of things will also be updated
(like the list of executables in the @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 updated 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. This dialog also allows you to change the name of the
scenario variable. This name is the same as the environment variable that
is used to set the initial value of the scenario variable.

@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 Extending Projects
@section Extending Projects
@cindex projects, extending
@c --------------------------------------------------------------------

@subsection Description of extending projects

@noindent
The project files were designed to support big projects, with several
hundreds or thousands of source files. In such contexts, one developer
will generally work on a subset of the sources. It is also not rare for
such a project to take several hours to fully compile. Most developers
therefore do not need to have the full copy of the project compiled on
their own machine or personal disk space.

However, it is still useful to be able to access other source files
of the application, for instance to find out whether a subprogram can be
changed and where it is currently called.

Such a setup can be achieved through extending projects. These are
special types of projects that inherit most of their attributes and source
files from another project, and can have, in their source directories, some
source files that hide/replace those inherited from the original project.

When compiling such projects, the compiler will put the newly created
project files in the extending project's directory, and will leave the original
untouched. As a result, the original project can be shared read-only among
several developers (for instance, it is usual for this original project to be
the result of a nightly build of the application).

@subsection Creating extending projects

@noindent
This project wizard allows you to easily create extending projects. You
should select an empty directory (which will be created automatically if
needed), as well as a list of source files you want to work on initially.
New files can also be added later.

As a result, GPS will copy the selected source files to the new directory
(if you so decided), and create a number of project files there. It will then
load a new project, which has the same properties as the previous
one, except that some files are found transparently in the new directory,
and object files resulting from the compilation are create into that
directory as opposed to the object directory of the original project.

@subsection Adding files to extending projects
@cindex Add To Extending Project

@noindent
Once you have loaded an extending project in GPS, things work mostly
transparently. If you open a file through the @code{File->Open From Project}
dialog, the files found in the local directory of your extending project
will be picked up first.

The build actions will create object files in the extending project's
directory, leaving the original project untouched.

It might happen that you want to start working on a source file that you
had not added in the extending project when it was created. You can of course
edit the file found in the original project, provided you have write access
to it. However, it is generally better to edit it in the context of the
extending project, so that the original project can be shared among
developers.

This can be done by clicking on the file in the @code{Project View}, then
selecting the menu @code{Add To Extending Project}. This will popup a
dialog asking whether you want GPS to copy the file to the extending
project's directory for you. GPS might also create some new project files
in that directory if necessary, and automatically reload the project as
needed. From then on, if you use the menu @code{File->Open From Project},
GPS will first see the file from the extending project.

Note that open editors will still be editing the same file they were before,
so you should open the new file if needed.

@c -------------------------------------------------------------------
@node Project View
@section The Project View
@cindex project view
@c -------------------------------------------------------------------

@noindent
The project view, as mentioned in the general description of the
GPS window, is one of the views 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 project view 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 project view.

@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 project view 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 (a pen 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 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 Project/Edit 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{})

@item Project/Dependencies...
@cindex project dependency
This opens the dependencies editor (@pxref{The Project Dependencies Editor}).

@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 Build
This menu offers the submenu "Clean" which remove all object files and other
compilation artifacts associated to the current project.

@end table

@cindex saving projects
Any time one or several projects are modified, the contents of the
project view is automatically refreshed. No project is automatically
saved. This provides a simple way to temporarily test new values for
the project attributes.
Unsaved modified projects are shown with a special icon in the project
view, displaying a pen 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

Note that in all tree views in GPS, you can use the @key{+} and @key{-} keys
to expand and collapse nodes (e.g. projects and directories).

@c -------------------------------------------------------------------
@node Disabling Project Edition Features
@section Disabling Project Edition Features
@cindex project editing
@c -------------------------------------------------------------------

@noindent
The project files should generally be considered as part of the sources,
and thus be put under control of a version control system. As such, you
might want to prevent accidental editing of the project files, either
by you or some other person using the same GPS installation.

The main thing to do to prevent such accidental edition is to change
the write permissions on the project files themselves. On Unix systems,
you could also change the owner of the file. When GPS cannot write a
project file, it will report an error to the user.

However, the above doesn't prevent a user from trying to do some
modifications at the GUI level, since the error message only occurs when
trying to save the project (this is by design, so that temporary modification
can be done in memory).

You can disable all the project editing related menus in GPS by adding
special startup switches. The recommended way is to create a small batch
script that spawns GPS with these switches. You should use the following
command line:

@smallexample
   gps --traceoff=MODULE.PROJECT_VIEWER --traceoff=MODULE.PROJECT_PROPERTIES
@end smallexample

What these do it prevent the loading of the two GPS modules that are
responsible for project edition. However, this also has an impact on the
python functions that are exported by GPS, and thus could break some
plug-ins. Another solution which might apply in your case is simply to
hide the corresponding project-editing menus and contextual menus. This
could be done by creating a small python plugin for GPS
(@pxref{Customizing through XML and Python files}, which contains the
following code:

@smallexample
import GPS
GPS.Menu.get  ("/Project/Edit Project Properties").hide()
GPS.Contextual ('Edit project properties').hide()
GPS.Contextual ('Save project').hide()
GPS.Contextual ('Add configuration variable').hide()
@end smallexample

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

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 view, 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 project. On exit, the wizard asks whether the
newly created project should be loaded. If you select @code{Yes}, the new
project will replace the currently loaded project hierarchy.

You will get asked what information you would like to create the project from.
In particular, you can create a set of project files from existing Ada
sources.

@item New from template
This menu will open the project template wizard, allowing you to create a new
project using one of the project templates defined in GPS. @xref{Adding project
templates}.

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

@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
@anchor{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 Reload Project
@cindex reload project
@cindex C
@cindex C++
Reload the project from the disk, to take into account modifications done
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.

@item Project View
Open (or raise if it is already open) the project view 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 typical way to access this wizard is through the
@code{Project->New...} menu.

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

@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 type
@item Project Naming
@item Languages Selection
@item Version Control System Selection
@item Source Directories Selection
@item Build Directory
@item Main Units
@item Library
@item Naming Scheme
@item Switches
@end itemize

@c ------------------------------------------------------------------
@subsection Project Type
@c ------------------------------------------------------------------

@noindent
Several types of project wizards are provided in GPS. Depending on the
information you have or your current setup, you will choose one or the
other.

@itemize @bullet
@item Single Project

This is likely the wizard you will use most often. It creates a project
file from scratch, and asks you for the location of source directories,
the object directory, @dots{}; The rest of this chapter describes this wizard
in more details

@item Project Tree

This wizard will attempt to create a set of one or more project files to
represent your current build environment. It will analyze what
your sources are, where the corresponding object files are, and will try
and find some possible setup for the project files (remember that a given
@file{.gpr} project file can be associated with a single object directory.

This wizard might not work in all cases, but is worth a try to get you
started if you already have an existing set of sources

@item Convert GLIDE Project (.adp)

This wizard will help you convert a @file{.adp} project file that is used
by the GLIDE environment. The same restrictions apply as above, except
that the list of source directories, object directories
and tool switches are read directly from that file.

@item Library Project
@cindex project, library

This specialized wizard is similar to the Single Project wizard, except it
adds one extra page, the Library page. The output of the compilation of this
project is a library (shared or static), as opposed to an executable in the
case of @code{Single Project}.

@item Extending Project
@cindex project, extending

This specialized wizard allows you to easily create extending projects
(@pxref{Extending Projects}).

@end itemize

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

@noindent
This is the first page displayed by any of 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.

Child projects can be created from this dialog. These are project whose
name is of the form @code{Parent.Child}. GPS will automatically generate
the dependency to the parent project so as to make the child project
valid.

In this page, you should also select what languages the source files
in this project are written in. Currently supported languages 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 Languages Selection
@cindex Languages
@c ------------------------------------------------------------------

@noindent
This page is used to select the programming languages used for the
sources of this project. By default, only @code{Ada} is selected.
New languages can be added to this list by using XML files, see the
section on customizing GPS (@pxref{Adding support for new languages}).

Additionally, this page allows you to select the toolchain used when working on
your project. There you can select one of the pre-defined toolchains or scan
your system for installed toolchains. You can also manually define some of the
tools in the toolchain such as the debugger to use, the gnat driver to use or
the gnatls tool to use.

If you need to select a toolchain for a cross environment, you should have a
look at @ref{Working in a Cross Environment} for more info on this subject.

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

@noindent
The second page in the project wizard allows you to select which Version
Control system is to be used for the source files of this project.

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

The two actions @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 other developers 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 a directory in the
top frame, and click on the down arrow. This will add the directory to
the bottom frame, which contains the current list of source directories.

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

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

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

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

@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 (e.g. @file{.o} files) are placed.
One object directory is associated for each project.

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

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

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

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

These files are treated specially by GPS. Some sub-menus of
@code{Build} and @code{Debug} will have predefined entries for the
main units, which makes 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 Library
@cindex library projects
@c ------------------------------------------------------------------

@noindent
This page allows you to configure your project so that the output of
its compilation is a library (shared or static), as opposed to an
executable or a simple set of objet files. This library can then be linked
with other executables (and will be automatically if the project is imported
by another one.

You need to define the attributes in the top box to transform your project
into a library project. See the tooltips that appear when you leave your
mouse on top of the label to the left of each field.

If you define any of the attributes in the Standalone Library box, you
will compile a standalone library. This is a library that takes care of
its elaboration by itself, instead of relying on its caller to elaborate
it as is standard in Ada. You also have more control over what files make
up the public interface to the library, and what files are private to the
library and invisible from the outside.

@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 this respect, and allows you to specify the
default extension for the files in a given programming language. GPS makes a
distinction between spec (or header) files, which generally contain
no executable code, only declarations, and body files which contain
the actual code. For languages other than Ada, this header file is
used rather than the body file when you select @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 this 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 fields at the bottom of
the window, and press the update button.

@cindex multi-unit source files
GNAT and GPS both support Ada source files that contain multiple Ada
units (typically a single file would contain both the spec and the body
of the unit for instance). This is not a recommend approach if you can
avoid it, since that might trigger unnecessary recompilation of your
source files. Such source files are always handled as naming scheme
exceptions, and you can specify those in the editor by adding "at 1",
"at 2",@dots{} after the file name for either the spec, the body or
both. The digit after "at" is the index (starting at 1) of the unit
in the source file.

For instance, specifying "file.ada at 1" for the spec and "file.ada at 2"
for the body of the unit "unit" indicates that the two components of the
unit are in the same file, first the spec, followed by the body.

@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 Dependencies Editor
@section The Project Dependencies Editor
@cindex project dependencies
@c -------------------------------------------------------------------

@noindent
You can edit the dependencies between projects through the contextual
menu @code{Project->Dependencies...} in the Project View.

This view makes it easy to indicate that your project depends on external
libraries, or other modules in your source code. For instance, you can
give access to the GtkAda graphical library in your project by adding
a project dependency to gtkada.gpr, assuming GtkAda has been installed
in your system.

The dependencies also determine in what order your application is built.
When you compile a project, the builder will first make sure that the projects
it depends on are up-to-date, and otherwise recompile them.

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

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

When you select that contextual menu, GPS will open a dialog that allows
you to add or remove dependencies to your project. New dependencies are
added by selecting a project file name from one of several sources:

@itemize @bullet
@item One of the loaded project from the current project tree

@item One of the predefined projects

   These are the projects that are found in one of the directories referenced
   in the @code{ADA_PROJECT_PATH} environment variable. Typically, these
   include third party libraries, such as GtkAda, win32ada, @dots{}

@item A new project created through the project wizard

@item Any project file located on the disk

@end itemize

In all these cases, you will generally be able to choose whether this should
be a simple dependency, or a limited dependency. The latter allows you to have
mutually dependent projects (A depends on B, which in turns depends on A
even indirectly), although you cannot reference the attribute of such a project
in the current project (for instance to indicate that the compiler switches
to use for A are the same as for B -- you need to duplicate that information).

In some cases, GPS will force a limited dependency on you to avoid loops in
the dependencies that would make the project tree illegal.

@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 project. 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 you can do directly from the pop-up dialog.

Fix the project file as you would for any text file, and then reload
it manually (through the @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

The project properties editor is divided in three parts:

@table @b
@item The attributes editor
The contents of this editor are 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.

See also @ref{Working in a Cross Environment} for more info on the
@code{Cross environment} attributes.

@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 cannot 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 view.

@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 the attributes editor apply.

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

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

@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 time 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.3cm}
@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 view, 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 View}.

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

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

Some new items are added to the menu:

@table @command
@item Locate in Project View
@cindex locate in Project View
Selecting this item will switch the focus to the project view, 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 projects it imports directly, 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
displays all the projects that directly import 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 view (on the left side of the main GPS
window), @dots{}
@cindex project view

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

By default, the search window is floating, ie appears as a dialog on top of
GPS. You can choose to put it inside the multiple document interface
permanently for easier access. This can be done by selecting the menu
@code{Window->Floating}, and then drag-and-dropping the search window in a
new location if you wish (for instance above the Project View).

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, 5cm}
@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.
@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. If several contexts are possible for one component (for example, the
editor has "Current_File", "Files from Project", "Files..." and "Open Files"),
then the last one you've been using will be selected. You can of course change
the context to another one if needed.

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

@table @code
@item Project View
Search in the project view. An extra @i{Scope} box will be displayed
where you can specify the scope of your search, which can be a set of:
@code{Projects, Directories, Files, Entities}. The search in entities
may take a long time, search each file is parsed during the search.

@item Open Files
Search in all the files that are currently open in the source editor. The
@i{Scope} entry is described in the @code{Files...} section below.

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

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

@item Files From Project
Search in all the files from the project, including files from project
dependencies. The @i{Scope} entry is described in the @code{Files...}
section above.

@item Current File
Search in the current source editor.
The @i{Scope} entry is described in the @code{Files...} section above.

@item Project Browser
Search in the project browser (@pxref{The Project Browser}).

@end table

The default value for @code{Look In} is set through various means: by
default, GPS will select a context that matches the currently selected
window. For instance, if you are in an editor and open the search dialog,
the context will be set to @code{Current File}. But if the project view is
the active window, the context will be set to @code{Project View}.
Optionally, GPS can remember the last context that was set (see the preference
@code{Search/Preserve Search Context}. If this is set, and an editor is
selected, GPS will remember whether the last time you started a search from
an editor you decided to search in @code{Current File} or @code{Files From
Project} for instance.

Finally, you can create key shortcuts (through the @code{/Edit/Key Shortcuts}
menu, in the @code{Search} category) to open the search dialog and set the
context to a specific value.

@end table

The second part of the window is a row of buttons, to start the search
(or continue to the next occurrence), and to display the options.

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

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

There are five check boxes in this options box.

@table @b
@item @code{"Regexp"}
@cindex regular expression
This button commutes between fixed string patterns and regular
expressions. You can also commute between these two modes
by selecting the arrow on the right of the @code{Search for:} field.
The grammar followed by the regular expressions is similar to the Perl and
Python regular expressions grammar, and is documented in the GNAT run time file
@file{g-regpat.ads}. To open it from GPS, you can use the open from project
dialog (@code{File->Open From Project...}) and type g-regpat.ads. See
@ref{Open From Project} for more information on this dialog.

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

@item @code{Select on Match}
@cindex select window on match
When this button is selected, the focus is given to the editor that contains
the match, so that you can start editing the text immediatly. If the button is
not selected, the focus is left on the search window, so that you can press
Enter to search for the next occurrence.

@item @code{Close on Match}
@cindex close dialog on match
This button only appears if the search window is floating. If this button is
enabled, the search window will be automatically closed when an
occurrence of the search string is found.

@item @code{"Case Sensitive Search"}
@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{"Case Preserving Replace"}
@cindex case preserving
When this is checked, replacements preserve casing. Three casings are detected
and preserved: all lower, all UPPER, and Mixed_Case where the first character
of each word is capitalized. Note that when the replace pattern is not all
lower case, replacement is never case-preserving, the original casing of the
replace pattern is used.

@end table

Pressing the @code{Find} / @code{Previous} buttons performs an interactive
search.
It stops as soon as one occurrence of the pattern is found.
search. Once a first occurrence has been found, the @code{Find} button is
renamed to @code{Next}.
You then have to press the @code{Next} button (or the equivalent shortcut
@key{Ctrl-N}) to go to the next occurrence.

If you use the @code{Find all} button, the search widget will start
searching for all occurrences right away, and put the results in a new
window called @code{Locations}, @xref{The Locations View}.

The @code{Replace} and @code{Replace & Find} buttons are grayed out as long as
no occurence of the pattern is found. In order to enable them, you have to
start a search, e.g. by pressing the @code{Find} button. Pressing @code{Replace}
will replace the current occurence (and therefore the two buttons will be
grayed out), and @code{Replace & Find} will replace the occurence and then
jump to the next one, if any. If you don't want to replace the current
occurence, you can jump directly to the next one by pressing @code{Next}.

The @code{Repl all} button will replace all the occurences found. By default,
a popup is displayed and ask for confirmation. It's possible to disable this
popup by either checking the box "Do not ask this question again", or by going
in the Search pannel of the preferences pages, and unchecking "Confirmation for
'Replace all'". The confirmation popup can be reenabled through this checkbox.

@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 More->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 View}, allowing you to easily navigate through the compiler
messages (see @ref{The Locations View}), or even to automatically correct some
errors or warnings (see @ref{Code Fixing}).

Compiler messages also appear as icons on the side of lines in the source
editors. When the mouse pointer is left on these icons, a tooltip appears,
listing the error messages found on this line. When GPS is capable of
automatically correcting the errors, clicking on the icon will apply the
fix to the source code. The icons on the side of editors are removed when
the corresponding entries are removed from @ref{The Locations View}.

@menu
* The Build Menu::
* The Target Configuration Dialog::
* The Build Mode::
* Working with two compilers::
@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.
note that this menu is fully configurable via the @code{Targets} dialog,
so what is documented in this manual are the default menus.

See @ref{The Target Configuration Dialog}.

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

@item Check Semantic
Check the semantic of the current source file. Display an error message in
the @i{Messages} window if no file is currently selected.

@item Compile File
Compile the current file.
By default, will display an intermediate dialog where you can add extra
switches, or simply press @key{Enter} to get the standard (or previous)
switches.
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 View. 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
View using either the contextual menu (@code{Remove category}) or by closing
the Locations View.

@item Project
   @table @i
   @item Build <main>
   The menu will list of all mains defined in your project hierarchy.
   Each menu item will build the selected main.

   @item Build All
   Build and link all main units defined in your project.
   If no main unit is specified in your project, build all files defined
   in your project and subprojects recursively.
   For a library project file, compile sources and recreate the library
   when needed.

   @item Compile All Sources
   Compile all source files defined in the top level project.

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

   @item Custom Build...
   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. If the @code{SHELL} environment
   variable is defined (to e.g. @code{/bin/sh}), then the syntax used to
   execute the command is the one for this shell. Otherwise, the command
   will be spawned directly by GPS without any shell interpretation.

   @end table

@item Clean
   @table @i
   @item Clean All
   Remove all object files and other compilation artifacts associated to all
   projects related to the current one. It allows to restart a complete build
   from scratch.

   @item Clean Root
   Remove all object files and other compilation artifacts associated to the
   root project. It does not clean objects from other related projects.
   @end table

@item Makefile
If you have a file called @file{Makefile} in the same directory as your
project file is, or if you've set the @code{makefile} property in the
@code{Make} section of the project properties (see
@ref{The Project Properties Editor}), this menu will be displayed, giving
access to all the targets defined in your makefile.

@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{External Commands->Execute command}).

   The GPS execution windows have several limitations compared to external
   terminals. In particular, they do not handle signals like @key{ctrl-z}
   and @key{control-c}. In general, if you are running an interactive
   application, we strongly encourage you to run in an external terminal.

   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.
   If the @code{SHELL} environment
   variable is defined (to e.g. @code{/bin/sh}), then the syntax used to
   execute the command is the one for this shell. Otherwise, the command
   will be spawned directly by GPS without any shell interpretation.

   @end table

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

@item Load xref info in memory
@cindex C
@cindex C++
Load all the cross-reference information in memory. This menu is generally
not needed, @xref{Support for Cross-References}.

@item Settings
   @table @i
   @item Targets
     @cindex Targets
     This opens the Target Configuration Dialog.
     @xref{The Target Configuration Dialog}.

   @item Toolchains
     @cindex Toolchains
     Open a dialog allowing the configuration of GPS for working with two
     compilation toolchains. This is particulary useful when compiling a
     project with an old compiler, while wanting up-to-date functionalities
     from the associated tools (gnatmetric, gnatcheck and so on).
     @xref{Working with two compilers}.
   @end table
@end table

The @code{Tools->Interrupt} menu can be used to interrupt the last compilation
or run command. Once you have interrupted that last operation, you can
interrupt the previous one by selecting the same menu again.

However, the easiest way to interrupt a specific operation, no matter if it was
started last or not, is to use the @code{Task Manager}, through the
@code{Tools->Views->Tasks} menu. It will show one line per running process,
and right-clicking on any of these lines gives the possibility to interrupt
that process.

If your application is build through a Makefile, you should probably load
the @file{Makefile.py} startup script (see the menu @code{/Tools/Plug-ins}).

@node The Target Configuration Dialog
@section The Target Configuration Dialog
@cindex Targets

@noindent
GPS provides an interface for launching operations like building projects,
compiling individual files, performing syntax or semantic checks, and so on.
All these operations have in common that they involve launching an external
command, and parsing the output for error messages. In GPS, these operations
are called "Targets", and can be configured either through the Target
Configuration dialog, or through XML configuration.
@xref{Customizing build Targets and Models}.

@iftex
@cindex screen shot
@image{target-configuration-dialog, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{target-configuration-dialog}
@end ifhtml

This dialog is divided in two areas: on the left, a tree listing Targets, and,
in the main area, a panel for configuring the Target which is currently
selected in the tree.

@subsection The Targets tree

The Tree contains a list of targets, organized by categories.

On top of the tree are three buttons:

@itemize @bullet
@item The Add button creates a new target.
@item The Remove button removes the currently selected target. Note that only
 user-defined targets can be removed, the default targets created by GPS cannot
 be removed.
@item The Clone button creates a new user-defined target which is identical
 to the currently selected target.
@end itemize

@subsection The configuration panel

On top of the configuration panel, one can select the Target model.
The Model determines the graphical options available in the
"Command line" frame.

The "Revert" button resets all target settings to their original value.

The "Options" frame contains a number of options that are available for all
Targets.

@itemize @bullet
@item The Launch mode indicates the way the target is launched:
  @itemize @bullet
  @item Manually:
    the target is launched when clicking on the corresponding icon
    in the toolbar, or when activating the corresponding menu item.
    In the latter case, a dialog is displayed, allowing last-minute
    modifications of the command line.

  @item Manually with dialog:
    same as Manually, but the dialog is always displayed, even when
    clicking on the toolbar icon.

  @item Manually with no dialog:
    same as Manually, but the dialog is never displayed, even when
    activating the menu item.

  @item On file save:
    the Target is launched automatically by GPS when a file is saved.
    The dialog is never displayed.

  @item In background:
    the Target is launched automatically in the background after each
    modification in the source editor. See @code{Background compilations}
    below.

  @end itemize

@item Target type: type of target described. If empty, or set to
  @code{Normal}, represents a simple target. If set to another value,
  represents multiple subtargets.
  For example, if set to @code{main}, each subtarget corresponds
  to a Main source as defined in the currently loaded project.
  Other custom values may be defined, and then handled via the
  @code{compute_build_targets} hook.

@end itemize

The "Display" frame indicates where the launcher for this target should be
 visible.

@itemize @bullet
@item in the toolbar: when active, a button is displayed in
  the main toolbar, allowing to quickly launch a Target.

@item in the main menu: whether to display a menu item corresponding
  to the Target in the main GPS menu. By default, Targets in the "File"
  category are listed directly in the Build menu, and Targets in other
  categories are listed in a submenu corresponding to the name of the category.

@item in contextual menus for projects: whether to display an item in the
  contextual menu for projects in the Project View

@item in contextual menus for files: whether to display an item in the
  contextual menus for files, for instance in file items in the Project View
  or directly on source file editors.

@end itemize

The "Command line" contains a graphical interface for some configurable
 elements of the Target, which are specific to the Model of this Target.

The full command line is displayed at the bottom. Note that it may contain
Macro Arguments. For instance if the command line contains the string "%PP",
GPS will expand this to the full path to the current project. For a full
list of available Macros, see @ref{Macro arguments}.

@subsection Background compilations

GPS is capable of launching compilation targets in the background. This means
that GPS will launch the compiler on the current state of the file in the
editor.

Error messages resulting from background compilations are not listed in the
Locations view or the Messages window. The full messages are listed in the
Background Build console, accessible from the menu @code{Tools->Console}.
Error messages which contain a source location indication are shown as icons
on the side of lines in editors, and the exact location is highlighted directly
in the editor. On both of these places, tooltips show the contents of the error
messages.

Messages from background compilations are removed automatically either when a
new background compilation has finished, or when a non-background compilation
is launched.

GPS will launch background compilations for all targets that have a
@code{Launch mode} set to @code{In background}, after modifications occur in
a source editor. Background compilation is useful mostly for targets such as
@code{Compile File} or @code{Check Syntax}. For targets that work on Mains,
the last main that was used in a non-background is considered, defaulting to
the first main defined in the project hierarchy.

Background compilations are not launched while GPS is already listing results
from non-background compilations, ie as long as there are entries in the
Locations View showing entries in the @code{Builder results} category.

@node The Build Mode
@section The Build Mode
@cindex Mode

@noindent
GPS provides an easy way to build your project with different options, through
the Mode selection, located in the main toolbar.

When the Mode selection is set to @code{default}, the build is done using the
switches defined in the project. When the Mode selection is set to another
value, then specialized parameters are passed to the builder. For instance, the
@code{gcov} Mode adds all the compilation parameters needed to instrument the
produced objects and executables to work with the @code{gcov} tool.

In addition to changing the build parameters, the Mode selection has the effect
of changing the output directory for objects and executables. For instance,
objects produced under the @code{debug} mode will be located in the
@code{debug} subdirectories of the object directories defined by the project.
This allows switching from one Mode to another without having to erase the
objects pertaining to a different Mode.

It is possible to define new Modes using XML customization, see
@ref{Customizing build Targets and Models}.

Note that the Build Mode affects only builds done using recent versions of
gnatmake and gprbuild. The Mode selection has no effect on builds done through
Targets that launch other builders.

@node Working with two compilers
@section Working with two compilers
@cindex Toolchains

@noindent
This functionality is intended for people whose projects need to be compiled
with a specific (old) version of the GNAT toolchain, while still desiring
to take full advantage of up-to-date associated tools for non-compilation
actions, such as checking the code against a coding standard, getting better
cross-reference browsing in GPS, computing metrics and so on.

GPS now allows you to handle this case. To configure GPS to make it handle two
compiler toolchains, you need to use the @code{Build->Settings->Toolchains}
menu. This will open a dialog where you can activate the multiple-toolchains
mode.

@iftex
@cindex screen shot
@image{toolchains-config, 9.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{toolchains-config}
@end ifhtml

In this dialog, two paths need to be configured: the compiler path and the
tools path. The first one is used to actually compile the code, while the
second one is used to run up-to-date tools to get more functionalities or
accurate results.

Note that GPS will only enable the @code{OK} button when the two paths
are set to different location, since otherwise it does not make sense to
enable the multiple toolchains set up.

From this dialog, you can also activate an automated cross-reference
generation. The cross-reference files are the .ali files generated by the
GNAT compiler together with the compiled object. Those files are used by GPS
for several functionalities, such as cross-reference browsing or documentation
generation. Having those .ali files produced by a recent compiler helps having
more accurate results with those functionalities, but might interract badly
with an old compiler also reading those .ali files for compiling a project.

If the automated xref generation is activated, then GPS will generate those
.ali files using the compiler found in the tools path, and place them in a
directory distinct from the one used by the actual compiler. This allows
GPS to take full benefit of up-to-date cross-reference files, while keeping the
old toolchain happy as its .ali files remain untouched.

Note that the cross-reference files generation does not output anything in the
"Messages" window, so as to not confuse the output of the regular build
process. If needed, you can see the output of the cross-ref generation command
by selecting the @code{Tools->Consoles->Auxiliary Builds} menu.

@subsection Interaction with the remote mode

The ability to work with two compilers has impacts on the remote mode
configuration: paths defined here are local paths, so they have no meaning
on the server side.

To handle the case of using a specific compiler version on the remote side
while still wanting up-to-date tools, the following behavior is applied when
both a remote compilation server is defined, and the multiple toolchains mode
is activated:

@itemize
@item The compiler path is ignored when a remote build server is defined. All
 compilation actions are then performed normally on the build server.
@item The tools path is however taken into account, and all related actions
 are performed on the local machine using this path.
@item The cross-reference files are taken care of by the rsync mechanism
 so that they don't get overwritten during local and remote host
 synchronisations, as build and cross-reference generation actions occur at
 the same time, on the local machine and on the distant server.
@end itemize

@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 Exporting
@cindex export
@cindex image
@cindex png
@cindex svg
The entire contents of a browser can be exported as a @code{PNG} image
using the entry @code{Export to PNG...} in the background contextual menu.
It can also be exported in @code{SVG} format using the @code{Export to SVG...}
entry.

@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 unselected items
Selecting this menu will remove all the items that are not currently
selected. This is a convenient method to clean up the contents of the
browser.

@item Remove selected items
Selecting this menu will remove all the items that are currently selected.

@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
view and source editor, by selecting one of the items:

All boxes in this browser list several information: the location of their
declaration, and the list of all their references in the other entities
currently displayed in the browser. If you close the box for an entity that
calls them, the matching references are also hidden, to keep the contents
of the browser simpler.

@table @command
@item Browsers->@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 Browsers->@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 Project View
Selecting this menu entry will move the focus to the project view,
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
project view and the source editor, 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 Recompute dependencies
@cindex recompute dependencies

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

It also recomputes the layout of the graph, and will change the current
position of the boxes.

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

@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 view 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
project view and source editor, when clicking on an entity:

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

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

After the debugger has been initialized, you have access to two new windows:
the data window (in the top of the working area), and the debugger console
(in a new page, after the Messages and Shell windows).
All the menus under @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 Current}, that will terminate your current debug
session, or the menu @code{Debug->Terminate} that will terminate all your
debug sessions at once.

@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::
* Customizing the Debugger::
@end menu

@c --------------------------------------------------------------------
@node The Debug Menu
@section The Debug Menu
@cindex menu
@cindex debug
@cindex debugger
@c --------------------------------------------------------------------

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

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

   @item Step
@cindex step
Execute the program until it reaches a different source line.

   @item Step Instruction
@cindex stepi
Execute the program for one machine instruction only.

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

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

   @item Finish
@cindex finish
Continue execution until selected stack frame returns.

   @item Continue
@cindex continue
Continue execution of the program being debugged.

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

   @item Terminate Current
@cindex terminate
Terminate the current debug session
by terminating the underlying debugger (e.g @code{gdb}) used
to handle the low level debugging. You can control what happens to the
windows through the @code{Debugger/Debugger Windows} preference.

   @item Terminate
@cindex terminate
Terminate all your debug sessions. Same as @code{Terminate Current} if there
is only one debugger open.

@end table

@subsection Debug

@table @b

   @item Connect to Board...
@cindex connect
@cindex board
@cindex target
@cindex cross debugger
Opens a simple dialog to connect to a remote board. This option is only
relevant to cross debuggers.

   @item Load File...
@cindex load

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

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

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

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

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

   @item Kill
@cindex kill
Kills the process being debugged.

@end table

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

@table @b
   @item Data Window
      Displays the Data window. If this window already exists, it is raised so
      that it becomes visible

   @item Call Stack
@cindex call stack
      Displays the Call Stack window.
      See @ref{The Call Stack Window} for more details.

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

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

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

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

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

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

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

   @item Assembly
@cindex assembly
      Opens a new window displaying an assembly dump of the current code
      being executed.
      See @ref{The Assembly Window} for more details.

   @item Edit Breakpoints
@cindex breakpoint
      Opens an advanced window to create and modify any kind of breakpoint,
      including watchpoints (see @ref{The Breakpoint Editor}).
      For simple breakpoint creation, see the description of the source window.

   @item Examine Memory
@cindex memory view
      Opens a memory viewer/editor. See @ref{The Memory Window} for more
      details.

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

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

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

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

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

   @item Recompute
@cindex recompute
      Recomputes and refreshes all the items displayed in the Data Window.
@end table

@c --------------------------------------------------------------------
@node The Call Stack Window
@section The Call Stack Window
@cindex call stack
@c --------------------------------------------------------------------

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

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

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

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

@cindex contextual menu
   The contextual menu (right mouse button) allows you to choose which
   information you want to display in the call stack window (via check buttons):
   @itemize @bullet
      @item Frame number: the debugger frame number (usually starts at 0 or 1)
      @item Program Counter: the low level address corresponding to the
            function's entry point.
      @item Subprogram Name: the name of the subprogram in a given frame
      @item Parameters: the parameters of the subprogram
      @item File Location: the filename and line number information.
   @end itemize

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

@c --------------------------------------------------------------------
@node The Data Window
@section The Data Window
@cindex data
@cindex data window
@c --------------------------------------------------------------------

@c --------------------------------------------------------------------
@subsection Description
@c --------------------------------------------------------------------

@noindent

The Data Window is the area in which various information about the debugged
process can be displayed. This includes the value of selected variables, the
current contents of the registeres, the local variables, @dots{}

@cindex Data Window
This window is not open by default when you start the debugger. It will be
created automatically when needed (e.g. when using the Debug constextual menu
to display a variable). You can also force its display through the menu
@code{Debug->Data->Data Window}.

However, if you save the desktop through the menu
@code{File->Save More->Desktop} while the data window is open, it will be
automatically reopen the next time the desktop is loaded, for instance when
restarting GPS.

The contents of the data window is preserved by default whenever you close it.
Thus, if you reopen the data window either during the same debugger session,
or automatically when you start a debugger on the same executable, it will
display the same items again. This behavior is controlled by the
@code{Preserve State on Exit} preference.

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

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

@iftex
@cindex screen shot
@image{canvas, 9.8cm}
@end iftex

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

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

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

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

     @item An icon representing an 'X'.
@cindex icon
       You can click on this icon to close/delete any box.
     @end itemize

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

@cindex contextual menu
   A contextual menu, that takes into account the current component selected
   by the mouse, gives access to the following capabilities:
   @table @b
     @item Close @i{component}
Closes the selected item.

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

     @item Show all @i{component}
@cindex show
Shows all subcomponents of the selected item.

     @item Clone @i{component}
@cindex clone
Clones the selected component into a new, independent item.

     @item View memory at address of @i{component}
@cindex memory view
Brings up the memory view dialog and explore memory at the address of the
component.

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

     @item Update Value
@cindex update value
Refreshes the value displayed in the selected item.

     @item Show Value
@cindex show value
Shows only the value of the item.

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

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

@c ??? Should have screen shot with value + type

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

   @end table

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

     @item Align On Grid
@cindex align
Enables or disables alignment of items on the grid.

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

     @item Zoom in
@cindex zoom in
Redisplays the items in the data window with a bigger font

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

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

     @item Clear
@cindex clear
When this item is selected, all the boxes currently displayed are removed.

   @end table

@c --------------------------------------------------------------------
@subsection Manipulating items
@c --------------------------------------------------------------------

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

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

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

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

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

@table @b

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

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

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

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

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

@end table

@subsubsection Icons
@cindex icon
@noindent
Several different icons can be used in the display of items. They also
convey special meanings.

@table @b

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

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

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

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

@end table

@c --------------------------------------------------------------------
@node The Breakpoint Editor
@section The Breakpoint Editor
@cindex breakpoint editor
@cindex breakpoint
@c --------------------------------------------------------------------

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

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

@noindent
@cindex menu
The breakpoint editor can be accessed from the menu
@i{Data->Edit Breakpoints}. It allows manipulation of different kinds
of breakpoints: at a source location, on a subprogram, at an executable
address, on memory access (watchpoints), and on Ada exceptions.

You can double-click on any breakpoint in the list to open the corresponding
source editor at the right location. Alternatively, you can select the
breakpoint and then click on the @code{View} button.

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

It is possible to access advanced breakpoint characteristics for a given
breakpoint.  First, select a breakpoint in the list.  Then, click
on the @i{Advanced} button, which will display a new dialog window.
You can specify commands to run automatically after a breakpoint
is hit, or specify how many times a selected breakpoint will be ignored.
If running VxWorks AE, you can also change the Scope and Action settings
for breakpoints.

@iftex
@cindex screen shot
@image{bp-advanced, 8.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{bp-advanced}
@end ifhtml

@subsection Scope/Action Settings for VxWorks AE
@cindex VxWorks AE

@noindent
In VxWorks AE breakpoints have two extra properties:

@itemize @bullet
@item Scope:
@cindex scope
 which task(s) can hit a given breakpoint. Possible Scope values are:
 @itemize @minus
  @item task:
@cindex task
   the breakpoint can only be hit by the task that was active when the
   breakpoint was set. If the breakpoint is set before the program is
   run, the breakpoint will affect the environment task
  @item pd:
@cindex protection domain
   any task in the current protection domain can hit that breakpoint
  @item any:
   any task in any protection domain can hit that breakpoint. This
   setting is only allowed for tasks in the Kernel domain.

 @end itemize

@item Action:
@cindex action
 when a task hits a breakpoints, which tasks are stopped:
 @itemize @minus
  @item task:
@cindex task
   stop only the task that hit the breakpoint.
  @item pd:
@cindex protection domain
   stop all tasks in the current protection domain
  @item all:
   stop all breakable tasks in the system

 @end itemize
@end itemize

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

@itemize @bullet

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

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

@end itemize

@cindex saving breakpoints
@cindex breakpoints, saving
If you have enabled the preference @code{Preserve state on exit}, GPS will
automatically save the currently set breakpoints, and restore them the next
time you debug the same executable. This allows you to immediately start
debugging your application again, without reseting the breakpoints every time.

@c --------------------------------------------------------------------
@node The Memory Window
@section The Memory Window
@cindex memory view
@c --------------------------------------------------------------------

@iftex
@cindex screen shot
@image{memory-view, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{memory-view}
@end ifhtml

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

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

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

@cindex key
The @i{up} and @i{down} arrows as well as the @key{Page up} and @key{Page down}
keys in the memory text area allows you to walk through the memory in
order of ascending/descending addresses respectively.

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

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

@c --------------------------------------------------------------------
@node Using the Source Editor when Debugging
@section Using the Source Editor when Debugging
@cindex source file
@cindex editing
@cindex debug
@c --------------------------------------------------------------------

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

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

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

@iftex
@cindex screen shot
@image{tooltips, 12.7cm}
@end iftex

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

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

@cindex contextual menu
   When the debugger is active, the contextual menu of the source window
   contains a sub menu called @code{Debug} providing the following entries.

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

   @table @b
     @item Print @i{selection}
@cindex print
Prints the selection (or by default the name under the cursor) in the
debugger console.

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

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

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

     @item View memory at address of @i{selection}
@cindex memory view
Brings up the memory view dialog and explores memory at the address of the
selection.

     @item Set Breakpoint on Line @i{xx}
@cindex breakpoint
Sets a breakpoint on the line under the cursor, in the current file.

     @item Set Breakpoint on @i{selection}
Sets a breakpoint at the beginning of the subprogram named @i{selection}

     @item Continue Until Line @i{xx}
@cindex continue until
Continues execution (the program must have been started previously) until
it reaches the specified line.

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

   @end table

@c --------------------------------------------------------------------
@node The Assembly Window
@section The Assembly Window
@c --------------------------------------------------------------------

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

You can open the assembly window by using the menu
@code{Debug->Data->Assembly}.

@iftex
@cindex screen shot
@image{assembly, 12.7cm}
@end iftex

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

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

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

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

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

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

@cindex example
@smallexample
output /x $eax
@end smallexample

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

@c --------------------------------------------------------------------
@node The Debugger Console
@section The Debugger Console
@cindex debugger
@cindex debugger console
@c --------------------------------------------------------------------

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

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

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

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

@table @command
@item graph (print|display) expression [dependent on display_num] [link_name name] [at x, y] [num num]
@cindex graph print
@cindex graph display
This command creates a new item in the canvas, that shows the value of
@var{Expression}. @var{Expression} should be the name of a variable, or one
of its fields, that is in the current scope for the debugger.

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

The new item is associated with a number, that is visible in its title bar.
This number can be specified through the @code{num} keyword, and will be taken
into account if no such item already exists.
These numbers can be used to create links between the items, using the
second argument to the command, @var{dependent on}. The link itself (i.e. the
line) can be given a name that is automatically displayed, using the third
argument.

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

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

@cindex example
@smallexample
graph display `print /x my_variable`
@end smallexample

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

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

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

Using the @code{graph enable} command will force the item to be automatically
refreshed every time the debugger stops, whereas the @code{graph disable}
command will freeze the item.

@item graph undisplay display_num
@cindex graph undisplay
This command will remove an item from the canvas

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

@end table

@c --------------------------------------------------------------------
@node Customizing the Debugger
@section Customizing the Debugger
@cindex debugger
@c --------------------------------------------------------------------

@noindent
GPS is a high-level interface to several debugger backends, in particular gdb.
Each back end has its own strengths, but you can enhance the command line
interface to these backends through GPS, using Python.

This section will provide a small such example. The idea is to provide the
notion of "alias" in the debugger console. For example, this can be used so
that you type "foo", and this really executes a longer command, like displaying
the value of a variable with a long name.

@code{gdb} already provides this feature through the @code{define} keywords,
but we will in fact rewrite that feature in terms of python.

GPS provides an extensive Python API to interface with each of the running
debugger. In particular, it provides the function "send", which can be used
to send a command to the debugger, and get its output, and the function
"set_output", which can be used when you implement your own functions.

It also provides, through @code{hook}, the capability to monitor the state of
the debugger back-end. In particular, one such hook,
@code{debugger_command_action_hook} is called when the user has typed a
command in the debugger console, and before the command is executed. This can
be used to add your own commands. The example below uses this hook.

Here is the code:

@smallexample
import GPS

aliases=@{@}

def set_alias (name, command):
   """Set a new debugger alias. Typing this alias in a debugger window
      will then execute command"""
   global aliases
   aliases[name] = command

def execute_alias (debugger, name):
   return debugger.send (aliases[name], output=False)

def debugger_commands (hook, debugger, command):
   global aliases
   words = command.split()
   if words[0] == "alias":
      set_alias (words[1], " ".join (words [2:]))
      return True
   elif aliases.has_key (words [0]):
      debugger.set_output (execute_alias (debugger, words[0]))
      return True
   else:
      return False

GPS.Hook ("debugger_command_action_hook").add (debugger_commands)
@end smallexample

The list of aliases is stored in the global variable @code{aliases}, which
is modified by @code{set_alias}. Whenever the user executes an alias, the
real command send to the debugger is sent through @code{execute_alias}.

The real part of the work is done by @code{debugger_commands}. If the user
is executing the @code{alias} command, it defines a new alias. Otherwise, if
he typed the name of an alias, we really want to execute that alias. Else,
we let the debugger back-end handle that command.

After you have copied this example in the @file{$HOME/.gps/plug-ins} directory,
you can start a debugger as usual in GPS, and type the following in its
console:

@smallexample
   (gdb) alias foo print a_long_long_name
   (gdb) foo
@end smallexample

The first command defines the alias, the second line executes it.

This alias can also be used within the @code{graph display} command, so that
the value of the variable is in fact displayed in the data window automatically,
for instance:

@smallexample
   (gdb) graph display `foo`
@end smallexample

Other examples can be programmed. You could write complex python functions,
which would for instance query the value of several variables, and pretty
print the result. This complex python function can then be called from the
debugger console, or automatically every time the debugger stops through the
@code{graph display} command.

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

@menu
* The VCS Explorer::
* The VCS Activities::
* The VCS Menu::
* The Version Control Contextual Menu::
* Working with global ChangeLog file::
* The Revision View::
@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 properties
editor. @xref{The Project Properties Editor}.

GPS does not come with any version control system: it uses underlying
command-line systems such as Subversion or ClearCase to perform
the low level operations, and provides a high level user interface on
top of them. Be sure to have a properly installed version control
system before enabling it under GPS.

The systems that are supported out of the box in GPS are:

@table @b
@item Auto
@cindex VCS, auto
GPS can be setup to auto-detect the actual VCS to use for each
project. This is done by selecting @code{Auto} in the @code{VCS} tab
of the Project properties editor. @xref{The Project Properties Editor}.
This is also the default behavior when no VCS is specified in the project.

@item ClearCase
@cindex VCS, ClearCase

The standard ClearCase interface, which is built-in and uses a generic GPS
terminology for VCS operations.

Note that, at the moment, only Snapshot Views are supported in the
ClearCase integration; Dynamic Views are not supported.

@item ClearCase Native
@cindex VCS, ClearCase Native

Which is fully customizable and uses by default the terminology
specific to ClearCase.

Note that, at the moment, only Snapshot Views are supported in the
ClearCase integration; Dynamic Views are not supported.

@item CVS
@cindex VCS, CVS

The Concurrent Version System.

GPS needs a corresponding @command{patch} command that usually comes with it.

@item Git
@cindex VCS, Git

Distributed fast source code management. Support for Git on GPS is
partial. Basic commands are supported but the full power of Git (like
working with the index) is only available on the command line.

GPS needs a corresponding @command{diff} command that usually comes with it.

@item Subversion
@cindex VCS, Subversion

The Subversion version control system. Note that on Windows this
version is intended to be used with Cygwin/Subversion and fully supports the
Cygwin path names.

GPS needs a corresponding @command{patch} and @command{diff} command
that usually comes with it.

@item Subversion Windows
@cindex VCS, Subversion Windows

The Windows native Subversion version control system. The external
Subversion commands are expected to be built for the Win32
subsystem. This version does not support Cygwin path names.

GPS needs a corresponding @command{patch} and @command{diff} command
that usually comes with it.
@end table

The default VCS that GPS will use is "Auto" by default, and this can be
 configured through @ref{The Preferences Dialog}.

It is also possible to add your own support for other version control systems,
or modify one of the existing interfaces, see
@ref{Adding support for new Version Control Systems} for more information.

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.

@cindex password
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. A file edited in GPS will be automatically added on the VCS
Explorer with a Modified status (see below).

@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 Project / File
This is a two levels tree, the first level contains the name of the
project and the second the name of files inside the project. Next to
the project name the VCS name, if any, is displayed. This is the only
information available for a project. The columns described below are for
the files only. This column can be sorted by clicking on the header.

@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
@iftex
@image{gps-vcs-unknown}
@end iftex
@ifhtml
@image{gps-vcs-unknown}
@end ifhtml
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
@iftex
@image{gps-vcs-not-registered}
@end iftex
@ifhtml
@image{gps-vcs-not-registered}
@end ifhtml
The file is not known to the VCS repository.

@item Up-to-date
@iftex
@image{gps-vcs-up-to-date}
@end iftex
@ifhtml
@image{gps-vcs-up-to-date}
@end ifhtml
The file corresponds to the latest version in the corresponding branch
on the repository.

@item Added
@iftex
@image{gps-vcs-added}
@end iftex
@ifhtml
@image{gps-vcs-added}
@end ifhtml
The file has been added remotely but is not yet updated in the local
view.

@item Removed
@iftex
@image{gps-vcs-removed}
@end iftex
@ifhtml
@image{gps-vcs-removed}
@end ifhtml
The file still exists locally but is known to have been removed from
the VCS repository.

@item Modified
@iftex
@image{gps-vcs-modified}
@end iftex
@ifhtml
@image{gps-vcs-modified}
@end ifhtml
The file has been modified by the user or has been explicitly opened
for editing.

@item Needs merge
@iftex
@image{gps-vcs-needs-merge}
@end iftex
@ifhtml
@image{gps-vcs-needs-merge}
@end ifhtml
The file has been modified locally and on the repository.

@item Needs update
@iftex
@image{gps-vcs-needs-update}
@end iftex
@ifhtml
@image{gps-vcs-needs-update}
@end ifhtml
The file has been modified in the repository but not locally.

@item Contains merge conflicts
@iftex
@image{gps-vcs-has-conflicts}
@end iftex
@ifhtml
@image{gps-vcs-has-conflicts}
@end ifhtml
The file contains conflicts from a previous update operation.
@end table

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

@item Activity
The name of the activity the file belongs to. See @ref{The VCS Activities}
for more details.

@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. It is also possible to
select files having the same status using the @code{Select files same status}
menu entry. See @ref{The Version Control Contextual Menu}.

@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 Activities
@section The VCS Activities
@cindex VCS activities
@cindex version control
@noindent

The VCS Activities give the ability to group files to be committed
together. The set of files can be committed atomically if supported by
the version control system used.

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

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

The way to bring up the VCS Activities view is through the
@code{VCS->Activities} menu.

The VCS Activities view contains the following columns:

@table @b
@item Activity / File
The name of the activity or files belonging to an activity. This
column can be sorted by clicking on the header.

@item Status
Shows the status of the file. This column can be sorted by clicking on
the header. See @ref{The VCS Explorer} for a full description.

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

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

There are different contextual menu entries depending on the
position on the screen.
On an empty area we have a simple contextual menu:

@table @b
@item Create new activity
Create a new activity. The name can be edited by double clicking on it.
@end table

On an activity line the contextual menu is:

@table @b
@item Group commit
This is a selectable menu entry. It is activated only if the
VCS supports atomic commit and absolute filenames. See @ref{The VCS node}
for full details.

@item Create new activity
Create a new activity. The name can be edited by double clicking on it.

@item Re-open activity / Close activity
If the activity is closed it is possible to re-open it and if it is
opened it is possible to close it manually.

@item Delete activity
Remove the activity.

@item Commit activity
Commit the activity. If group commit is activated then the commit log
content is generated using a template file fully configurable.
See @ref{Files}.
If group commit is not activated then the log content for each
activity file is the file log catenated with the activity log. After
this operation the file's log are removed but the activity log is kept
as documentation.

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

@item Update
Update all the source files contained in the activity.

@item Compare against head revision
Show a visual comparison between the local activity files and the most recent
version of those files in the repository.

@item Build patch file
Create a patch file (in text format) for the activity. The patch file
contains a header (the activity log and file's logs) and the diff of
each file. The header format is fully configurable using a template
file. See @ref{Files}.

@item Edit revision log
Edit the current revision log for activity. This log is shared with
all the activity files.

@item Remove revision log
Remove the current revision log for activity. This menu is present
only if the activity revision log exists.
@end table

On a file line the contextual menu contains:

@table @b
@item Create new activity
Create a new activity. The name can be edited by double clicking on
it.

@item Remove from activity
Remove the selected file from the activity and delete the
activity log.

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

@end table

@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
@code{Tools->Views->Files}.
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 Create tag...
Create a tag or branch tag starting from a specific root
directory. The name of the tag is a simple name.

@item Switch tag...
Switch the local copy to a specific tag. The name of the tag depends
on the external VCS used. For CVS this this the simple tag name, for
Subversion the tag must conform to the default repository layout. For
a branch tag this is @code{/branches/<tag_name>/<root_dir>}.
@end table

For a description of the other entries in the VCS menu, see
@ref{The Version Control Contextual Menu}

@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 view, 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 Remove project
Only displayed on a project line. This will remove the selected
project from the VCS Explorer.

@item Expand all
Expand all VCS Explorer project nodes.

@item Collapse all
Collapse all VCS Explorer project nodes.

@item Clear View
Clear the VCS Explorer.

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

@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 Open
@anchor{Open}
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 entire revision history
@anchor{View revision history}
Show the revision logs for all previous revisions of this file.

@item View specific revision history
Show the revision logs for one previous revision of this file.

@item Compare against head revision
@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 other revision
@anchor{Compare against working}
Show a visual comparison between the local file and one specific
version of that file in the repository.

@item Compare two revisions
@anchor{Compare against revision}
Show a visual comparison between two specific revisions
of the file in the repository.

@item Compare base against head
@anchor{Compare base 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 Compare against tag/branch
@anchor{Compare base against tag/branch}
Only available on a Revision View and over a tag/branch. Show a visual
comparison between the corresponding version of the file in the
repository and the version of that file in the tag/branch.

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

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

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

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

@item Edit global ChangeLog
Edit the global ChangeLog entry for the selected file.
@pxref{Working with global ChangeLog file}.

@item Remove revision log
Clear the current revision associated to the selected file.

@item Add
Add a file to the repository, using the current revision log for this
file. If no revision log exists, activating this menu will create
one. The file is committed in the repository.

@item Add/No commit
Add a file to the repository, using the current revision log for this
file. If no revision log exists, activating this menu will create
one. The file is not committed in the repository.

@item Remove
Remove a file from the repository, using the current revision log for
this file. If no revision log exists, activating this menu will create
one. The modification is committed in the repository.

@item Remove/No commit
Remove a file from the repository, using the current revision log for
this file. If no revision log exists, activating this menu will create
one. The modification is not committed in the repository.

@item Revert
Revert a locale file to the repository revision, discarding all local
changes.

@item Resolved
Mark files' merge conflics as resolved. Some version control systems
(like Subversion) will block any commit until this action is called.

@item Switch tag/bracnh
Only available on a Revision View and over a tag/branch name. Will
switch the tree starting from a selected root to this specific tag or
branch.

@item Merge
Only available on a Revision View and over a tag/branch name. Merge
file changes made on this specific tag/branch.

@item View revision
Only available on a Revision View and over a revision.

@item Commit as new Activity
An action to prepare a group-commit in just one-click. This action will:

@itemize @bullet
@item create an anonymous activity,
@item add all files selected into the VCS Explorer into the newly
created anonymous activity,
@item open the activity log,
@end itemize

Just fill the activity log and commit the anonymous activity.

@item Add to Activity
A menu containing all the current activities. Selecting one will add
the current file to this activity. This menu is present only if the
file is not already part of an activity.

@item Remove from Activity
Remove file from the given activity. This menu is present only if the
file is already part of an activity.

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

@table @i
@item Add/No commit
Add the selected directory into the VCS.

@item Remove/No commit
Remove the selected directory from the VCS.

@item Commit
Commit the selected directory into the VCS. This action is available
only if the VCS supports commit on directories, @pxref{The VCS node}.

@item Add to Activity
Add the selected directory into the VCS. This action is available
only if the VCS supports commit on directories, @pxref{The VCS node}.

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

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

@item Query status for directory recursively
Query status for the files in the selected directory and all
subdirectories recursively. Links and hidden directories are not
included.

@item Update directory recursively
Update the files in the selected directory and all
subdirectories recursively. Links and hidden directories not included..

@end table

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

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

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

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

@item List all files in project and sub-projects
Bring up the VCS Explorer with all the source files contained in the
project and all imported sub-projects.

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

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

@end table

@item Select files same status
Select the files having the same status as the current selected file.

@item Filters
Only available from the VCS Explorer. This menu controls filtering of the
items displayed in the list.

@table @i
@item Show all status
Do not filter out any file from the list in the VCS Explorer.

@item Hide all status
Filter out all the files from the list in the VCS Explorer.

@item Show <status>
When disabled, filter out the files with the given status from the VCS
Explorer.
@end table

@end table

@node Working with global ChangeLog file
@section Working with global ChangeLog file
@cindex global ChangeLog
@cindex ChangeLog file
@noindent

A global ChangeLog file contains revision logs for all files in a
directory and is named @file{ChangeLog}. The format for such a file
is:

@smallexample
   @b{ISO-DATE  @i{name  <e-mail>}}

   <HT>* @b{filename}[, @b{filename}]:
   <HT>revision history
@end smallexample

where:

@table @b
@item ISO-DATE
A date with the ISO format YYYY-MM-DD

@item name
A name, generally the developer name

@item <e-mail>
The e-mail address of the developer surrounded with '<' and '>' characters.

@item HT
Horizontal tabulation (or 8 spaces)
@end table

The @i{name} and @i{<e-mail>} items can be entered automatically by setting
the @var{GPS_CHANGELOG_USER} environment variable. Note that there is
two spaces between the @i{name} and the @i{<e-mail>}.

@smallexample
On sh shell:

   export GPS_CHANGELOG_USER="John Doe  <john.doe@@home.com>"

On Windows shell:
   set GPS_CHANGELOG_USER="John Doe  <john.doe@@home.com>"
@end smallexample

Using the menu entry @b{Edit global ChangeLog} will open the file
@file{ChangeLog} in the directory where the current selected file is
and create the corresponding @file{ChangeLog} entry. This means that
the ISO date and filename headers will be created if not yet
present. You will have to enter your name and e-mail address.

This @file{ChangeLog} file serve as a repository for revision logs,
when ready to check-in a file use the standard @b{Edit revision log}
menu command. This will open the standard revision log buffer with the
content filled from the global @file{ChangeLog} file.

@node The Revision View
@section The Revision View

@noindent
The revision view is used to display a revision tree for a given
file. Each node contains information for a specific revision of
the file.

@iftex
@cindex screen shot
@image{revision-view, 13.5cm}
@end iftex

@ifhtml
@cindex screen shot
@image{revision-view}
@end ifhtml

@table @b

@item the revision number
This corresponds to the external VCS revision number.

@item author
The author of this revision.

@item date / log
For root nodes this column contains the check-in date and eventually
the list of tags and branches associated with this revision. For
children nodes this contains the log for the corresponding revision.

@end table

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

@menu
* The Tools Menu::
* Coding Standard::
* Visual Comparison::
* Code Fixing::
* Documentation Generation::
* Metrics::
* Code Coverage::
@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 Views

@table @b

@item Bookmarks
@cindex bookmark
@xref{Bookmarks}.

@item Call Trees
Open a tree view of function callers and callees. See also @ref{Call Graph}.

@item Clipboard
@xref{The Clipboard View}.

@item Coverage Report
@xref{Coverage Report}.

@item Entities
Open the Entity View in the bottom area
@xref{The Entity View}.

@item Files
Open a file system explorer on the left area.
@xref{The File View}.

@item File Switches
@xref{File Switches}.

@item Outline
Open a view of the current source editor.
@xref{The Outline View}.

@item Project
@xref{The Project View}.

@item Remote
@xref{Setup a remote project}.

@item Scenario
@xref{Scenarios and Configuration Variables}.

@item Tasks
@xref{The Task Manager}.

@item VCS Activities
@xref{The VCS Activities}.

@item VCS Explorer
@xref{The VCS Explorer}.

@item Windows
Open a view containing all currently opened files.
@xref{The Window View}.

@end table

@item Browsers

@table @b
@item Call Graph
@xref{Call Graph}.

@item Dependency
@xref{Dependency Browser}.

@item Entity
@xref{Entity Browser}.

@end table

@item Coding Standard
@cindex Coding Standard
@xref{Coding Standard}.

@item Compare
@cindex visual diff
@xref{Visual Comparison}.

@item Consoles
@table @b

@item GPS Shell
@cindex shell
Open a shell console at the bottom area of GPS. Note that this not an OS
shell console, but a GPS shell console, where you can type GPS specific
commands such as @code{help}.

@xref{The Shell and Python Windows}.

@item Python
@cindex python
Open a python console to access the python interpreter.
@xref{The Shell and Python Windows}.

@item OS Shell
@cindex shell
Open an OS (Windows or Unix) console, using the environment variables
@code{SHELL} and @code{COMSPEC} to determine which shell to use.
@xref{The Shell and Python Windows}.

On Unix, this terminal behaves a lot like a standard Unix terminal. In
particular, you need to make sure that your shell will output all the
information. In some cases, the configuration of your shell (@file{.bashrc}
if you are running bash for instance) will deactivate the echo of what you
type to the terminal. Since GPS is not outputing anything on its own, just
showing what the shell is outputing, you need to somehow ensure that your
shell always echos what you type. This is done by running the command

@smallexample
stty echo
@end smallexample

in such cases. In general, this can be safely done in your @file{.bashrc}

@item Auxiliary Builds
Open the console containing auxiliary builds output. For now, only
cross-reference automated generation output is redirected to this console.
@xref{Working with two compilers}.
@end table

@item Coverage
@cindex code coverage
@xref{Code Coverage}.

@item Documentation
@cindex documentation
@xref{Documentation Generation}.

@item Macro
@cindex macros
@xref{Recording and replaying macros}.

@item Metrics
@cindex metrics
@xref{Metrics}.

@item Plug-ins
@cindex plug-ins
@xref{The Plug-ins Editor}.

@item Interrupt
@cindex interrupt
Interrupt the last task launched (e.g. compilation, vcs query, @dots{}).

@end table

@node Coding Standard
@section Coding Standard
@cindex coding standard
@noindent

The Coding Standard menu allows you to edit your coding standard file, as can
be understood by gnatcheck, as well as run it against your code, to verifiy its
compliance with this coding standard.

Note that you can also use the contextual menu to check the conformance of
a particular project or source file against a Coding Standard.

The Coding standard editor is triggered by the menu Tools->Coding
Standard->Edit Rules File. The editor allows you to select an existing coding
standard file, or create a new one. The editor adapts itself to the version of
gnatcheck you are using on your local machine.

The currently used rules are summarized in the bottom of the editor. Once all
rules are defined, you can check the box 'Open rules file after exit' to
manually verify the created file.

Once the Coding Standard file is created, you can define it as the default
coding standard file for a project by going to the project editor, selecting
the 'Switches' tab, and using this file in the 'Gnatcheck' section.

@node Visual Comparison
@section Visual Comparison
@cindex visual diff
@noindent

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

The 2-file comparison tool is based on the standard text command
@command{diff}, available on all Unix systems. Under Windows, a default
implementation is provided with GPS, called @command{gnudiff.exe}.
You may want to provide an alternate implementation by e.g. installing a
set of Unix tools such as cygwin (@url{http://www.cygwin.com}).

The 3-file comparison tool is based on the text command @command{diff3},
available on all Unix systems. Under Windows, this tool is not shipped
with GPS. It is available as part of cygwin, for example.

When querying a visual comparison in GPS, in Side_By_Side mode, the user area
will show, side by side, editors for the files involved in the comparison.
The reference file is placed by default on the left side. When in Unified mode,
GPS will not open a new editor, but will show all the changes directly in the
original editor. Note that Unified mode is relevant only when comparing two
files: when comparing three files, the Side_By_Side mode is used.

Color highlighting will be added to the file editors:

@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 yellow
This color is used to display lines that have been modified compared to the
reference file. When there are fine differences within one line, they are
shown in a brighter yellow.

@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

These colors can be configured, @pxref{The Preferences Dialog}.

As with all highlighted lines in GPS, the visual differences highlights are
visible in the Speed Column at the left of the editors.

Blank lines are also added in the editors, in places that correspond to
existing lines in the other editors. The vertical and horizontal scrolling
are synchronized between all editors involved in a visual comparison.

When a visual comparison is created, the Locations View is populated with the
entries for each chunk of differences, and can be used to navigate between
those.

Closing one of the editors involved in a visual comparison removes the
highlighting, blank lines, and scrolling in the other editors.

Editors involved in a visual comparison have a contextual menu
@code{Visual diff} that contains the following entries:

@table @code
@item Recompute
Regenerates the visual comparison. This is useful, for example, when one of
the editors has been modified by hand while it was involved in a visual
comparison

@item Hide
Removes the highlighting corresponding to the visual comparison from all
editors involved

@item Close editors
Closes all editors involved in this visual comparison

@item Use this editor as reference
Change the reference to this editor. (This is only visible when displaying a
visual comparison involving 3 files).

@end table

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

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

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

This capability is integrated with the @i{Locations View} (see
@ref{The Locations View}): 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, a wrench
icon with a blue @i{plus} sign is displayed.
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.

Right clicking on a message with a fix will open a contextual menu with an
entry "Auto Fix". Fixes that can be applied by clicking on the wrench are
available through that menu as well. In addiditon, if exactly one of the fixes
is considered to be safe by GPS, additional entries will be provided to apply
fixes on multiple messages:

@table @code
@item Fix all similar errors
Will apply the same simple fix for all errors which are detected by the system
as being the same kind. This is based on message parsing.

@item Fix all simple style errors and warnings
This entry is offered only when the selected message is a warning and a style
error. Will fix all other warnings and style errors for which a unique simple
fix is available.

@item Fix all simple errors
Will fix all errors messages for which a unique simple fix is available

@end table

@node Documentation Generation
@section Documentation Generation
@cindex documentation generation
@noindent

GPS provides a documentation generator which processes source files
and generates annotated HTML files.

It is based on the source cross-reference information (e.g. generated by
GNAT for Ada files). This means that you should ensure that cross-reference
information has been generated before generating the documentation.
It also relies on standard comments that it extracts from the source code.
Note that unlike other similar tools, no macro needs to be put in your
comments. The engine in charge of extracting them coupled with the
cross-reference engine gives GPS all the flexibility needed to generate
accurate documentation.

The documentation is put by default into a directory called @file{doc}, created
under the object directory of the root project loaded in GPS. If no such object
directory exists, then it is directly created in the same directory as the root
project. This behavior can be modified by specifying the attribute
Documentation_Dir in the package IDE of your root project:
@smallexample
project P is
   package IDE is
      for Documentation_Dir use "html";
   end IDE;
end P;
@end smallexample

Once the documentation is generated, the main documentation file is loaded
in your default browser.

The documentation generator uses a set of templates files to control the final
rendering. This means that you can control precisely the rendering of the
generated documentation. The templates used for generating the documentation
can be found under @file{<install_dir>/share/gps/docgen2}. If you need a
different layout as the proposed one, you can change directly those files.

In addition, user-defined structured comments can be used to improve the
generated documentation. The structured comments use xml-like tags. To define
your own set of tags, please refer to the GPS python extension documentation
(from GPS Help menu, choose 'Python extensions').

The string values inside those tags are handled very roughly the same way as in
regular xml: duplicated spaces and line returns are ignored. One exception is
that the layout is preserved in the following cases:
@table @code
@item The line starts with "- " or "* "
In this case, GPS makes sure that a proper line return precedes the line. This
is to allow lists in comments
@item The line starts with a capital letter
GPS then supposes that the preceding line return was intended, so it is kept
@end table

Some default tags have been already defined by GPS in
@file{<install_dir>/share/gps/plug-ins/docgen_base_tags.py}. The tags handled
are:

@table @code
@item summary
Short summary of what a package or method is doing.
@item description
Full description of what a package or method is doing.
@item parameter (attribute "name" is expected)
Description of the parameter named "name".
@item exception
Description of possible exceptions raised by the method.
@item seealso
Reference to another package, method, type, etc.
@item c_version
For bindings, the version of the C file.
@item group
For packages, this builds an index of all packages in the project grouped by
categories.
@item code
When the layout of the value of the node needs to be preserved. The text is
displayed using a fixed font (monospace).
@end table

The following sample shows how those tags are translated:
@smallexample
--  <description>
--    This is the main description for this package. It can contain a complete
--    description with some xml characters as < or >.
--  </description>
--  <group>Group1</group>
--  <c_version>1.0.0</c_version>
package Pkg is

   procedure Test (Param : Integer);
   --  <summary>Test procedure with a single parameter</summary>
   --  <parameter name="Param">An Integer</parameter>
   --  <exception>No exception</exception>
   --  <seealso>Test2</seealso>

   procedure Test2 (Param1 : Integer; Param2 : Natural);
   --  <summary>Test procedure with two parameters</summary>
   --  <parameter name="Param1">An Integer</parameter>
   --  <parameter name="Param2">A Natural</parameter>
   --  <exception>System.Assertions.Assert_Failure if Param1 < 0</exception>
   --  <seealso>Test</seealso>

end Pkg;
@end smallexample

Its documentation will be:

@iftex
@cindex screen shot
@image{docgen, 17cm}
@end iftex

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

@c For a description of the
@c documentation generator renderer @pxref{Defining a documentation format}.

The documentation generator can be invoked from two places inside GPS:

@table @b
@item @ref{The Tools Menu}

@table @command
@item Generate project
Generate documentation for all files from the loaded project.

@item Generate projects & subprojects
Generate documentation for all files from the loaded project as well all
its subprojects.

@item Generate current file
Generate documentation for the file you are currently editing.

@item Generate for...
This will open a File Selector Dialog (@pxref{The File Selector}) and
documentation will be generated for the file you select.

@end table

@item The Contextual Menu

When relevant (depending on the context), right-clicking with your mouse
will show a @code{Documentation} contextual menu.

From a source file contextual menu, you have one option called
@command{Generate for <filename>}, that will generate documentation
for this file and if needed its corresponding body
(@pxref{The Preferences Dialog}).

From a project contextual menu (@pxref{The Project View}), you will have the
choice between generating documentation for all files from the selected project
only or from the selected project recursively.

You will find the list of all documentation options in
@ref{The Preferences Dialog}.

Note that the documentation generator relies on the ALI files created by
GNAT. Depending on the version of GNAT used, the following restrictions may
or may not apply:

@itemize @bullet
@item A type named @i{type} may be generated in the type index.

@item Parameters and objects of private generic types may be considered as
types.
@end itemize
@end table

@node Metrics
@section Metrics
@cindex Metrics
@noindent

GPS provides an interface with the GNAT software metrics generation tool
@code{gnatmetric}.

The metrics can be computed for the entire project, one source file belonging to
the project, or (when applicable) a specific entity in the source file, e.g. a
subprogram.

The metrics generator can be invoked from two places inside GPS:

@table @b
@item @ref{The Tools Menu}

@table @command
@item Metrics->Compute metrics for root project
Generate metrics for all files from the root project.

@item Metrics->Compute metrics for current file
Generate metrics for the current source file.

@end table

@item The Contextual Menu

When relevant (depending on the context), right-clicking with your mouse
will show metrics-related contextual menu entries.

From a source file contextual menu, you have an option called
@command{Metrics for file} that will generate the metrics for
the current file.

From a project contextual menu (@pxref{The Project View}), you have an
option @command{Metrics for project} that will generate the metrics for
all files in the project.

@end table

Each of these commands produces a new window in the left-side area,
which shows the computed metrics as a hierarchical tree view. The metrics
are arranged by files, and then by scopes inside the files in a nested fashion.
Double-clicking on any of the files or scopes displayed will open the
appropriate source location in the editor. Any errors encountered during
metrics computation will be displayed in the Locations Window.

@c --------------------------------------------------------------------
@node Code Coverage
@section Code Coverage
@cindex Code Coverage
@noindent
@c --------------------------------------------------------------------

GPS is fitted with a strong integration of Gcov, the GNU code coverage
utility.

Code coverage information can be computed from, loaded and visualized in GPS.
This can be done file by file, for each files of the current project,
project by project (in case of dependencies) or for the entire project hierarchy
currently used in GPS.

Once computed then loaded, the coverage information is summarized in a
graphical report (shaped as a tree-view with percentage bars for each item)
and used to decorate source code through mechanisms such as line highlighting or
coverage annotations.

All the coverage related operations are reachable via the
@command{Tools->Coverage} menu.

In order to be loaded in GPS, the coverage information need to be computed
before, using the @command{Tools->Coverage->Gcov->Compute coverage files} menu
for instance.

At each attempt, GPS automatically tries to load the needed information and
reports errors for missing or corrupted @command{.gcov} files.

To be able to produce coverage information from Gcov, your project must have
been compiled with the @command{-fprofile-arcs} and @command{-ftest-coverage}"
switches, respectively "Instrument arcs" and "Code coverage" entries in
@ref{The Project Properties Editor}, and run once.

@table @b
@item @ref{The Tools Menu}

The @command{Tools->Coverage} menu have an incremental set of entries,
depending on the context.

@table @command

@item Coverage->Gcov->Compute coverage files
Generates the @command{.gcov} files of current and properly compiled and run
projects.

@item Coverage->Gcov->Remove coverage files
Deletes all the @command{.gcov} of current projects.

@c \hline

@item Coverage->Show report
Open a new window summarizing the coverage information currently loaded in GPS.

@c \hline

@item Coverage->Load data for all projects
Load or re-load the coverage information of every projects and subprojects.

@item Coverage->Load data for project @code{XXX}
Load or re-load the coverage information of the project @code{XXX}.

@item Coverage->Load data for @file{xxxxxxxx.xxx}
Load or re-load the coverage information of the specified source file.

@c \hline

@item Coverage->Clear coverage from memory
Drop every coverage information loaded in GPS.

@end table

@item The Contextual Menu

When clicking on a project, file or subprogram entity (including the entities
listed in the coverage report), you have access to a @command{Coverage} submenu.

These submenus contain the following entries, adapted to the context related
element. For instance, if you click on a file, you will have:

@table @command
@item Coverage->Show coverage information
Append an annotation column to the left side of the current source editor.
This column indicates which lines are covered and which aren't. Unexecuted lines
are also listed in the @ref{The Locations View}.

@item Coverage->Hide coverage information
Withdraw from the current source editor a previously set coverage annotation
column and clear @ref{The Locations View} from the eventually listed uncovered
lines.

@item Coverage->Load data for @file{xxxxxxxx.xxx}
Load or re-load the coverage information of the specified source file.

@item Coverage->Remove data of @file{xxxxxxxx.xxx}
Remove the coverage information of the specified source file from GPS memory.

@item Coverage->Show Coverage report
Open a new window summarizing the coverage information. (This entry appears
only if the contextual menu has been created from outside of the Coverage
Report.)
@end table

@item The Coverage Report
@anchor{Coverage Report}

When coverage information are loaded into GPS, a graphical report of coverage
is displayed.

This report contains a tree of Projects, Files and Subprograms with
corresponding coverage information for each node in sided columns.

@iftex
@cindex screen shot
@image{report-of-analysis_tree, 8.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{report-of-analysis_tree}
@end ifhtml

The contextual menus generated on this widget contain, in addition to the
regular entries, some specific Coverage Report entries.

These entries allow you to expand or fold the tree, and also to display flat
lists of files or subprograms instead of the tree. A flat list of file will
look like:

@iftex
@cindex screen shot
@image{report-of-analysis_flat, 8.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{report-of-analysis_flat}
@end ifhtml

@end table

GPS and Gcov both support many different programming languages, and so code
coverage features are available in GPS for many languages. But, note that
subprogram coverage details are not available for every supported languages.

To finish, note that if you change the current main project in GPS, using the
@command{Project->Open} menu for instance, you will also drop every loaded
coverage information as they are related to the working project.

@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{Cross environment} part of the @code{General} page, and
@code{Toolchains} part of the @code{Languages} page.

In the @code{Toolchains} section, you will typically either scan your system
to display found toolchains, and select the one corresponding to your cross
environment or use the Add button and manually select the desired cross
environment.

If needed, you can also modify manually some of the tools defined in this
toolchain in the @code{Details} part of the @code{Languages} page.

For example, assuming you have an Ada project, and using a powerpc VxWorks
configuration. Hitting the scan button, you should see the toolchain
@code{powerpc-wrs-vxworks} appearing in the @code{Toolchains} section.
Selecting this toolchain will change the @code{Details} part, displaying the
relevant tools (e.g. @i{Gnatls} to
@code{powerpc-wrs-vxworks-gnatls} and @i{Debugger} to
@code{powerpc-wrs-vxworks-gdb} @dots{}).

The list of toolchains and their default values that can be selected when using
the Add button can be modified via a custom xml file. See
@ref{Customizing and Extending GPS} and in particular
@ref{Toolchains customization} for further information.

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

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

@c --------------------------------------------------------------------
@node Using GPS for Remote Development
@chapter Using GPS for Remote Development
@cindex remote
@cindex network
@cindex client/server
@c --------------------------------------------------------------------
@menu
* Requirements::
* Setup the remote servers::
* Setup a remote project::
* Limitations::
@end menu

@noindent
In a network environment, it is common for programmers to use a desktop
computer that is not directly suitable for their development tasks. For
example, each developer may have a desktop PC running Windows or GNU/Linux
as their main entrypoint to the company network. They may do all their actual
development work using project resources shared on networked servers. These
remote servers may also be running an operating system that is different from
the one on their desktop machine.

A typical way of operating in such an environment is to access the server
through a remote windowing system such as X-Window. GPS does indeed work in
such a context but it is not necessarily the most efficient organization.
Running GPS remotely on a shared server will increase the workload of the
server as well as the traffic on the network. When the network is slow or
saturated, user interactions can become uncomfortably sluggish. This is
unfortunate because the desktop used to access the network is often a powerful
PC that remains idle most of the time. To address this situation, GPS offers
the option to run natively on the desktop, with compilation, run and/or debug
activities performed transparently on one or more remote servers.

@node Requirements
@section Requirements

@noindent
In order to compile, run or debug on a host remote from GPS, three conditions
must be met:

@itemize
@item
@cindex password
Have a remote connection to the host using 'rsh', 'ssh' or 'telnet'. Note that
GPS can now handle passwords for such connections.

@item
Have either a Network Filesystem (i.e. NFS, SMB or equivalent) sharing the
project files between the host and the target, or have rsync installed on
both client and server. Note that rsync can be found at
@url{http://www.samba.org/rsync/} for unix, and comes as part of cygwin under
Windows: @url{http://www.cygwin.com}.

@item
Subprojects must be 'withed' by the main project using relative paths, or the
same absolute paths must exist on the machines involved.
@end itemize

@noindent
The full remote development setup is performed in two broad steps:
@itemize
@item Setup the remote servers configuration.
@item Setup a remote project.
@end itemize

@c -----------------------------------------------------------------------
@node Setup the remote servers
@section Setup the remote servers
@c -----------------------------------------------------------------------

@menu
* The remote configuration dialog::
* Connection settings::
* Paths settings::
@end menu

@c -----------------------------------------------------------------------
@node The remote configuration dialog
@subsection The remote configuration dialog
@c -----------------------------------------------------------------------

@noindent
In order to configure remote servers, you need to open the remote
configuration dialog. A predefined configuration can also be set when
installing GPS, using xml files. @xref{Defining a remote server}, and
@xref{Defining a remote path translation}, for more information.

The remote configuration dialog is opened via the remote view. You can
open it using the menu @code{Tools->Views->Remote}.

@iftex
@cindex screen shot
@image{remote-view, 4.8cm}
@end iftex

@ifhtml
@cindex screen shot
@image{remote-view}
@end ifhtml

Once the Remote View is opened, click on @code{Settings} to open
the servers configuration dialog.

@iftex
@cindex screen shot
@image{servers-configuration, 11.5cm}
@end iftex

@ifhtml
@cindex screen shot
@image{servers-configuration}
@end ifhtml

@noindent
This dialog is composed of two parts:
@itemize
@item
The left part of the dialog contains the list of configured servers,
identified by their nickname. Three buttons allow you to create, reinitialize
or delete a server.
@item
The right part of the dialog contains the selected server's configuration.
@end itemize

You need first to create a new server. For this, click on the button
@code{Add Server} on the bottom left part of the dialog. Enter a nickname
identifying the server you want to connect to (this is not necessarily the
network name of this server). Note that this nickname identifies the server and
therefore must be unique. This new server is then automatically selected,
and the right part of the dialog shows its configuration, which is empty for
the most part.

@c -----------------------------------------------------------------------
@node Connection settings
@subsection Connection settings
@c -----------------------------------------------------------------------

The first configuration part that needs to be filled concerns the way
we will connect to this server:

You have to enter first all mandatory fields, identified by an asterisk:
@itemize
@item
The network name is the name used to connect to this server via your network.
It can be either an IP address, a host name of your local network, or a fully
qualified network name.
@item
The remote access tool is the tool used to connect to this server. You select
it using the drop down list. The following tools are supported natively by
GPS: ssh, rsh, telnet and plink (Windows tool) in ssh, rsh or telnet mode.
@xref{Defining a remote connection tool}, if you need to add a
specific tool.
Note also that if one of those tools is not installed (e.g. is not in
your path), then it won't appear in the tools list. Some tools incompatible
with GPS will not be displayed either, such as the Microsoft telnet client.
@item
The shell tells GPS what shell runs on the remote server. The following unix
shells are supported by GPS: sh, bash, csh and tcsh. Windows' shell is also
supported (cmd.exe). @xref{Limitations}, for cygwin's shell usage on
windows: it is preferable to use cmd.exe as a remote shell on Windows servers.
@end itemize

@noindent
Other fields might need to be taken into consideration, but they are not
mandatory. They are, for the most part, accessible through the advanced
configuration pane.

@itemize
@item
The remote sync tool is used to synchronize remote and local filesystems, if
these are not shared filesystems. For now, only rsync is supported.
@item
The Extra Init Commands field represents initialization commands sent to the
server upon connection: when GPS connects to your remote machine, the chosen
shell is launched, and your default initialization files are read (i.e. .bashrc
file for the bash shell). Then GPS sends these extra init commands, allowing
you for example to specify a compilation toolchain.
@item
(In Advanced configuration pane) The user name specifies the name used to
connect to the server. If unspecified, the remote access tool will typically
use your current login name. If not, and a user name is requested, GPS will
prompt you for a user name.
@item
(In Advanced configuration pane) The timeout value is used to determine if a connection to a remote host is
dead. All elementary operations performed on the remote host (i.e., operations
that normally complete almost immediately) will use this timeout value. By
default, this value is set to 10s. If you have a very slow network connection
or a very overloaded server, set this timeout to a higher value.
@item
(In Advanced configuration pane) The maximum number of connections determines the maximum number of simultaneous
connections GPS is allowed to have to this server. In fact, if you want to
compile, debug and execute at the same time on the machine, GPS will need
more that one connection to do this. The default value is 3.
@item
(In Advanced configuration pane) Depending on the kind of server and the remote
access tool used, commands sent to the server may require a specific line terminator,
i.e., either the LF character or CR/LF characters. Usually GPS can automatically detect what is needed
(the 'auto' mode), but the choice can be forced to CR/LF (cr/lf handling
set to 'on') or LF (cr/lf handling set to 'off').
@item
(In Advanced configuration pane) The Debug console allows you to easily
debug a remote connection. If checked, it will open a console
reporting all exchanges between GPS and the selected server.
@end itemize

@c -----------------------------------------------------------------------
@node Paths settings
@subsection Paths settings
@c -----------------------------------------------------------------------

The last configuration part defines the path translations between
your local host and the remote server.

The remote paths definition will allow GPS to translate your locally loaded
project (the project that resides in your local filesystem) to
paths used on the remote server. This part also tells GPS how to keep
those paths synchronized between the local machine and the remote server.

All your project's dependencies must then reside in a path that is defined
here. Note that you can retrieve those paths by using @code{gnat list
-v -Pyour_project}. In particular, the path to the GNAT run-time
(@code{adainclude} directory) needs to be mapped so that code completion and
source navigation work properly on run-time entities.

To add a new path, click on the @code{+} button, and enter the corresponding
local and remote paths.

You can easily select the desired paths by clicking on the icon next
to the path's entry. Remote browsing is allowed only when the
connection configuration is set (@xref{Connection settings}.) Clicking
on @code{Apply} will apply your connection configuration and allow you
to browse the remote host to select the remote paths.

Five kinds of path synchronization can be set for each defined path:
@itemize
@item @code{Never}: no synchronization is required from GPS, the paths
are shared using an OS mechanism like NFS.
@item @code{Manually}: synchronization is needed, but will only be performed
manually using the remote view buttons.
@item @code{Always}: Relevant to source and object paths of your project.
They are kept synchronised by GPS before and after every remote action (such
as performing a build or run).
@item @code{Once to local}/@code{Once to remote}: Relevant to project's
dependencies. They are synchronized once when a remote project is
loaded or when a local project is set remote. They can still be
manually synchronized using the Remote View (@xref{The remote view}.)
@end itemize

The way those paths need to be configured depends on your network architecture.

@itemize
@item
If your project is on a filesystem that is shared between your host and
the remote host (using NFS of SMB filestems, for example), then only the roots
of those filesystems need to be specified, using each server's native paths (on
Windows, the paths will be expressed using X:\my\mounted\directory\ while on
unix, the paths will be expressed using /mnt/path/).
@item
If the project's files are synchronized using rsync, defining a too generic
path translation will lead to very slow synchronization. In that case you
should define the paths as specifically as possible, in order to speed up
the synchronization process.
@end itemize

@c -----------------------------------------------------------------------
@node Setup a remote project
@section Setup a remote project
@cindex remote project
@c -----------------------------------------------------------------------

@menu
* Remote operations::
* The remote view::
* Loading a remote project::
@end menu

@c -----------------------------------------------------------------------
@node Remote operations
@subsection Remote operations
@c -----------------------------------------------------------------------

@noindent
GPS defines four different remote operation categories: Build operations,
Debug operations, Execution operations and Tools operations. All compiler
related operations are performed on the Build_Server. The Tools server is
somewhat special and will be explained later. The debugger is run on
the Debug_Server, and the project's resulting programs are run on the
Execution_Server. The GPS_Server (the local machine) is used for all
other operations.

The Tools server is defined to handle all compiler related operations that do
not depend on a specific compiler version. It is used in dual compilation mode,
for example, to determine whether the action can be safely run using a very
recent compiler toolchain (this is the tools server), or whether a specific
older baseline compiler version must be used.

In case the remote mode is activated, and the dual compilation mode is not,
all Tools server operations are executed on the build server. Otherwise, if the
dual compilation mode is activated, then the tools server operations are always
executed on the local machine.

@c -----------------------------------------------------------------------
@node The remote view
@subsection The remote view
@c -----------------------------------------------------------------------

The Remote view (@code{Tools->Views->Remote}) allows you to assign servers to
operation categories for the currently loaded project.  You may assign each
operation category a distinct server if the Servers assignment tab is fully
expanded. Alternatively, you may assign all categories to a single server in
one step if the Servers assignment tab is collapsed.

@iftex
@cindex screen shot
@image{remote-view-full, 4.8cm}
@end iftex

@ifhtml
@cindex screen shot
@image{remote-view-full}
@end ifhtml

@noindent
When a server is selected for a particular category, the change is not
immediately effective. To indicate that fact, the server's name will appear in
red. This approach allows you to check the configuration before applying it, by
pressing the @code{Check} button. This action will test for correct remote hosts
connection. It will also verify that the project path exists on the build server and
that it has an equivalence on the local machine.

Clicking on the @code{Apply} button will perform the following actions:
@itemize
@item Read the default project paths on the Build machine and translate them
into local paths.
@item Synchronize from the build server those paths marked as Sync @code{Always} or @code{Once to
local}.
@item Load the translated local project.
@item Assign the Build, Execution and Debug servers.
@end itemize

If one of the above operations fails, corresponding errors are reported in the
@code{Messages} view and the previous project settings are retained.

Once a remote server is assigned, this remote configuration will be
automatically loaded each time the project is loaded.

The two buttons on the right of each server can be used to manually perform
a synchronization from the remote host to your local machine (left
button) or from your local machine to the remote host (right button).

@c -----------------------------------------------------------------------
@node Loading a remote project
@subsection Loading a remote project
@c -----------------------------------------------------------------------

@noindent
If the project you want to work with is already on a distant server, you can
directly load it on your local GPS.

To do this, use the @code{Project->Open From Host} menu.
Then select the server's nickname. This will show you its file tree.
Navigate to your project and select it. The project will be loaded as described
above, with all remote operations categories assigned to the selected server by
default.

You can reload your project using the local files on your machine. The
remote configuration will then be automatically reapplied.

@c -----------------------------------------------------------------------
@node Limitations
@section Limitations
@c -----------------------------------------------------------------------

The GPS remote mode imposes a few limitations:

@itemize
@item Execution: you cannot use an external terminal to remotely execute your
application. The @code{Use external terminal} checkbox of the run dialog will
have no effect if the program is run remotely.

@item Debugging: you cannot use a separate execution window. The
@code{Use separate execution window} option is ignored for remote
debugging sessions.

@item Cygwin on remote host: the GNAT compilation toolchain does not
understand cygwin's mounted directories. In order to use GPS with
a remote Windows server using cygwin's bash, you need to use
directories that are the same on Windows and cygwin (absolute
paths). For example, a project having a C:\my_project will be accepted
if cygwin's path is /my_project, but will not be accepted if
/cygdrive/c/my_project is used.

Note that even if you use cygwin's sshd on such a server, you can
still access it using cmd.exe (@xref{Connection settings}.)
@end itemize

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

@menu
* The Preferences Dialog::
* GPS Themes::
* The Key Manager Dialog::
* The Plug-ins Editor::
* Customizing through XML and Python files::
* Adding support for new tools::
* Customization examples::
* Scripting GPS::
* Adding support for new Version Control Systems::
* The Server Mode::
* Adding project templates::
@end menu

@noindent
GPS provides several levels of customization, from simple preferences dialog
to powerful scripting capability through the @code{python} language.
This chapters describes each of these capabilities.

@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 several areas, accessible through the
tabs at the left of the dialog.
Each page corresponds to a set of preferences.

@itemize @bullet
@item @b{Themes}

This page allows you to quickly change the current settings for GPS, including
preferences, key bindings, menus@dots{}; See @ref{GPS Themes} for more
information on themes. It is only displayed when there are themes registered.

@item @b{General}

@table @i
@item Default font
@cindex font
@cindex background color
The default font used in GPS. The background color you select for this
preference will set the background color for all consoles and most views (the
ones that display their data as trees, mostly). To change the background color
of editors, see the preference Edit/Fonts&Colors/Default.

@item Fixed view font
@cindex font
The fixed (monospace) font used in views like the outline view, the bookmark
view, @dots{}; As much as possible, this font should use a fixed width for
characters, for a better rendering

@item Character set
@cindex character set
@cindex ISO-8859-1
Name of character set to use when reading or writting text files.
GPS uses UTF-8 and Unicode internally, which can handle any character in
any language. However, your system will generally not support Unicode natively,
and thus the contents of the files should be translated from the file system
encoding to unicode.

This preference indicates the file system encoding in use. It defaults to
ISO-8859-1, which corresponds to western european characters.

@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.
If you are working with a project created automatically by GPS, the desktop
will not be saved.

@item Save editor in desktop
@cindex desktop
Determines when source editors should be saved in the desktop: @code{Never},
@code{Always}, or when a source file is associated with the current project
(@code{From_Project}).

@item Multi language builder
The multi-language builder to be used in case a multi-language or non Ada
project has been loaded.

By default, @code{gprbuild} will be used. Alternatively, its prototype
@code{gprmake} can be selected to help the transition, although we do not
recommend it at this stage.

Finally, if you want to force the use of gnatmake, even for projects
that contain other sources, you can use the @code{gnatmake} setting. Note
that Gnatmake will only consider Ada files.

@item Jump to first location
@cindex location
Whether the first entry of the location window should be selected
automatically, and thus whether the corresponding editor should be
immediately open.

@item Wrap around on next/previous
@cindex location
Whether using the @code{Next Tag} and @code{Previous Tag} actions/menus
should wrap around to the beginning when reaching the end of the category.
The default is to wrap around, as was done in previous GPS versions.

@item Auto close Locations view
@cindex location
Whether the Locations view should be closed automatically when it becomes
empty.

@item Hyper links
@cindex hyper mode
Whether to display hyper links in the editors when the Control key is pressed.
@xref{Navigating with hyperlinks}.

@item Clipboard size
@cindex clipboard
This controls the size of the list where all the entries copied into the
clipboard through @code{Edit->Copy} and @code{Edit->Cut} are saved. This list
is navigated through the menu @code{Edit->Paste} and
@code{Edit->Paste Previous}, as described earlier in this guide.

@item Tool bar style
@cindex tool bar
How the tool bar should be displayed: not at all, with small icons or with
large icons

@item Show status bar
@cindex status bar
Whether the status bar at the bottom of the GPS window should be displayed.
This status bar contains one or more progress bars while GPS is executing long
actions like a build or a search. These progress bars can be used to monitor
the progress of those actions.

If you wish to save vertical screen space, you can hide this status
bar. The progress bars will no longer be visible. Instead, you can
display the Task Manager through the @code{Tools->Views->Tasks} menu,
to get similar information.  This manager can then be put on the right
or left side of the GPS window, for instance just below the Project
View.

@item Remove policy when fixing code
@cindex code fix
Prefered way to fix code when parts have to be removed.
@code{Always_Remove} means that the code will be removed by GPS.
@code{Always_Comment} means that the code will always be commented out.
@code{Propose_Both_Choices} will propose a menu with both choices.

@item Tip of the Day
@cindex tip of the day
Whether GPS will display a @i{Tip of the Day} dialog at start up.

@end table

@item @b{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 @i
@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 Short titles for floats
@cindex float
If True, all floating windows will have a short title. In particular, base
file names will be used for editors instead of full names.

@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 Show title bars
If Always, each window in GPS will have its own title bars, showing some
particular information (like the name of the file edited for editors), and
some buttons to iconify, maximize or close the window. This title bar is
highlighted when the window is the one currently selected.

If Never, the title bar is not displayed, to save space on the screen. The
tabs of the notebooks will then be highlighted.

If Central Only, then only the windows in the central area (ie the part that
gets preserved when switching perspective, mostly editors) will have a title
bar. All other windows will not show the title bar. This is often a good way
to save space on the screen: the title bar is useful for editors since it
gives the full name of the file as well as provide an easy handle for drag
and drop operations, whereas the other views do not change position as much
and it is better to save space on the screen by not displaying their title.

@item Notebook tabs policy
Indicates when the notebook tabs should be displayed. If set to "Never", you
will have to select the window in the Window menu, or through the keyboard.
If set to "Automatic", then the tabs will be shown when two or more windows
are stacked.

@item Notebook tabs position
Indicates where the notebook tabs should be displayed by default. It is
possible to select the position of tabs individually for each notebook
by right-clicking in any of their tabs and chosing a new position in the
contextual menu. This position will be saved as part of the desktop and
restored the next time you restart GPS. However, if you change the value
of this preference, all notebooks will reset the position of their tabs
to match the new value of the preference.

@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 Display subprogram names
@cindex Display subprogram names
Whether the subprogram name should be displayed in the editor's status bar.

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

@item Tooltips timeout
@cindex tooltip timeout
Time (in milliseconds) before displaying tooltips.

@item Highlight delimiters
@cindex highlight delimiter
Determine whether the delimiter matching the character following the
cursor should be highlighted. The list of delimiters includes: @code{@{@}[]()}

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

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

@item Right margin
@cindex right margin
The right margin to highlight. 0 if none.
This value is also used to implement the @code{Edit->Refill} command.

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

@item Block folding
@cindex block folding
Whether the editor should provide the ability to fold/unfold blocks.

@c @item Automatic syntax check
@c @cindex automatic syntax
@c Whether GPS should automatically check syntax in background for the source
@c files that are being edited.

@item Speed Column Policy
@cindex speed column policy
When the Speed Column should be shown on the side of the editors:
@table @code

@item Never
The Speed Column is never displayed.

@item Automatic
The Speed Column is shown whenever lines are highlighted in the editor, for
example to show the current execution point, or lines
containing compilation errors, @dots{};
It disappears when no lines are highlighted.

@item Always
The Speed Column is always displayed.

@end table

@item Use Windows ACL
This is a Windows specific preference which is disabled by default. When
enabled GPS will use the ACL to change the file's write permission. Note
that ACL can't be used on network drives.

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

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

@item Smart completion
@cindex smart completion
When enabled, GPS loads on startup all the information needed for the
Smart completion to work.

@item Smart completion timeout
The timeout, expressed in milliseconds, after which the Smart completion
window appears automatically after entering a triggering character, such as '.'

@end table

@item Fonts & Colors
@cindex font
@cindex color

@table @b
@item Default
The default font, default foreground and default background colors used
in the source editor.

@item Block
Font variant and colors used to highlight blocks (subprograms, task, entries,
...) in declarations.

@item Type
Font variant and colors used to highlight types in declarations.

@item Keywords
Font variant and colors used to highlight keywords.

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

@item Annotated  Comments
Font variant and colors used to highlight annotated comments.
Only relevant to Ada currently. Annotated comments are comments immediately
followed by a special character, e.g. @code{#[]}.
Setting the color to white will set a transparent color.

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

@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 Draw current line as a thin line
Whether to use a thin line rather than full background highlighting on the
current line.

@item Current block color
Color for highlighting the current source block.

@item Delimiter highlighting color
Color for highlighting delimiters.

@item Search results highlighting
Color for highlighting the search results in the text of source editors.

@item Cursor color
Color used for the cursor in editors and interactive consoles

@item Cursor aspect ratio
Defines the size of the cursor, relatively to characters. 100 means the
cursor will occupy the same size as a character, 10 means it will only
occupy 10% of the size occupies by a character.

@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.
Note that this preference does not modify the @key{Tab} key which will still
insert Tab characters. Consider also the @code{/Edit/Insert Tab With Spaces} key
shortcut which can be mapped (to e.g. @key{Tab}) via @ref{The Key Manager
Dialog}. Finally, another alternative is to reconfigure the default key
binding for the automatic indentation action: by default, it is mapped to
@key{Ctrl-Tab}
and can be changed to @key{Tab} by modifying the @code{/Edit/Format Selection}
action from @ref{The Key Manager Dialog}.

@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 Conditional continuation lines
@cindex conditional line
The number of extra spaces used to indent multiple lines conditionals
within parentheses.

For example, when this preference is set to 1 (the default), continuation
lines are indented based on the previous parenthesis plus one space:

@cindex example
@smallexample
if (Condition1
    and then Condition2)
then
@end smallexample

When this preference is set to 3, this gives:

@cindex example
@smallexample
if (Condition1
      and then Condition2)
then
@end smallexample

@item Record indentation
@cindex record indentation
The number of extra spaces for record definitions, when the @code{record}
keyword is on its own line.

For example, when this preference is set to 3 (the default), the
following sample will be indented as:

@cindex example
@smallexample
type T is
   record
      F : Integer;
   end record;
@end smallexample

When this preference is set to 1, this gives:

@cindex example
@smallexample
type T is
 record
    F : Integer;
 end record;
@end smallexample

@item 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{Non_Rm_Style}, this would be indented as:

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

By default (@code{Automatic}), GPS will choose to indent with an extra
level or not based on the first @code{when} construct: if the first
@code{when} is indented by an extra level, the whole case statement will
be indented following the RM style.

@item Casing policy
The way the editor will handle the case settings below.
@code{Disabled} no auto-casing will be done;
@code{End_Of_Line} auto-casing will be done when hitting @key{Enter} key;
@code{End_Of_Word} auto-casing will be done word-by-word while typing;
@code{On_The_Fly} auto-casing will be done character-by-character while typing.
For the @code{End_Of_Line}, @code{End_Of_Word} and @code{On_The_Fly} policies
it is always possible to force the casing of the current line by pressing the
indentation key (@key{Ctrl-Tab} by default).

It is also possible to disable the casing for a single character
(action @code{No Casing/indentation on Next Key}, default @key{Ctrl-Q}) or
temporarily (action @code{Toggle Auto Casing/indentation},
default @key{Alt-Q}).

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

@item Identifier casing
How the editor should handle identifiers casing.
The values are the same as for the @i{Reserved word casing} preference.

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

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

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

@item Align declarations after colon
Whether the editor should align continuation lines in variable declarations
based on the colon character.

Consider the following code:

@cindex example
@smallexample
Variable : constant String :=
  "a string";
@end smallexample

If this preference is enabled, it will be indented as follows:

@cindex example
@smallexample
Variable : constant String :=
             "a string";
@end smallexample

@item Indent comments
Whether to indent lines containing only comments and blanks, or to keep
these lines unchanged.

@item Align comments on keywords
Whether to align comment lines following @code{record} and
@code{is} keywords immediately with no extra space.

When enabled, the following code will be indented as:

@cindex example
@smallexample
package P is
--  Comment

   [...]
end P;
@end smallexample

When disabled, the indentation will be:

@cindex example
@smallexample
package P is
   --  Comment

   [...]
end P;
@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.

@item Indent comments
Whether to indent lines containing only comments and blanks, or to keep
these lines unchanged.

@end table

@end table

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

@item Preserve State on Exit
@cindex breakpoint
If this preference is enabled, the debugger will automatically save breakpoints
when it exists, and restore them the next time the same executable is debugged.
This is a convenient way to work on an executable, where the typical usage
looks like compile, debug, compile, debug, @dots{}

When the preference is enabled, the debugger will also preserve the contents
of the data window whenever it is closed. Reopening the window either during
the same debugger session, or automatically when a new debugger is started
on the same executable, will recreate the same boxes within the data window.

@item Debugger Windows
@cindex debugger windows
This preference controls what happens to debugger-related windows, like the
call stack, the data window, the tasks view,..., when the debugger is
terminated. There are three possible behavior:
@itemize @bullet
 @item Close Windows

In this case, all these windows are closed. This saves memory and space on
the screen, but you will need to explicitly reopen them and put them in the
right location on the desktop the next time you start a debugger session.

 @item Keep Windows

In this case, the windows are cleared, but kept on the desktop. When you
start a new debugger session, the windows will be automatically reused. This
ensures that you won't have to reopen and reposition them, but takes space
on your screen

 @item Hide Windows

The windows are cleared, and hidden. When you start a new debugger session,
they are automatically made visible again and reused. This also ensures you
will not have to reopen and reposition them, but requires a bit of memory.
If you move some windows around while these windows are hidden, they might
reappear in unexpected location the next time, although you then just have
to move them.

@end itemize

@item Break on exceptions
@cindex breakpoint
@cindex exception
Specifies whether a breakpoint on all exceptions should be set by
default when loading a program. This setup is only taken into account
when a new debugger is initialized, and will not modify a running
debugger (use the breakpoint editor for running debuggers).

@item Execution window
@cindex execution
@cindex tty
Specifies whether the debugger should create a separate execution
window for the program being debugged.

Note that this preference cannot be taken into account for the current
debug session: you need to terminate the current debug session and restart
a new one.

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 only interrupt the debugged program with recent versions of gdb.
If you are using older versions of gdb, you need to hit
@key{Ctrl-C} in the separate execution window to interrupt it while it is
running. Note also that this separate execution window uses the default
system-wide console properties (the size of the window, the
colors...). It is possible to change those properties using e.g. the
default console menu (top-left of the console) on Windows XP.

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 the source editor should display blue dots 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.

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

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

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

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

@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 in the data window that have
changed since the last update.

@item Memory color
Color used by default in the memory view window.

@item Memory highlighting
Color used for highlighted items in the memory view.

@item Memory selection
Color used for selected items in the memory view.

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

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

@item Max item width
The maximum width an item can have.

@item Max item height
The maximum height an item can have.

@end table

@item @b{External Commands}
@cindex helper
@cindex external commands
@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 HTML Browser
@cindex html
Only used under Unix, not relevant under Windows where the default HTML
browser is used.
Program used to execute view HTML files, for instance the documentation.
Empty by default, which means that GPS will try to find a suitable HTML
browser automatically. Only change the value if GPS cannot find a HTML
browser, or if the browser found is not your preferred one.

@item Print command
@cindex print
@cindex a2ps
@cindex PrintFile
@anchor{Print Command}
External program used to print files.

This program is required under Unix systems in order to print, and is set to
@code{a2ps} by default.
If @code{a2ps} is not installed on your system, you can download it
from @url{ftp://ftp.enst.fr/pub/unix/a2ps/}, although other printing programs
such as @code{lp} can be specified instead.

Under Windows systems, this program is optional and is empty by default, since
a built-in printing is provided. An external tool will be used if specified,
such as the PrintFile freeware utility available from
@url{http://www.lerup.com/printfile/descr.html}

@end table

@item @b{Search}
@cindex search
@table @b

@item Confirmation for "Replace all"
@cindex replace
Enable or disable the confirmation popup for the replace all action.

@item Close on Match
@cindex search
If this option is enabled, the search window will be closed when a match is
found.

@item Select on Match
@cindex search
If this option is enabled, the focus will be given to the editor when a match
is found.

@item Preserve Search Context
@cindex search
If this option is enabled, the contents of the "Look in:" field will be
preserved between consecutive searches in files.
@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}). This setting applies to most browsers (call graph
for instance), but does not apply to the entities browsers.

@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{VCS}
@cindex vcs

@table @i

@item Implicit status
@cindex Implicit status
Whether a status action can be launched as part of another action. For
example to get the revision numbers of new files after an update
command. If the network connection with the repository is slow
disabling this command can speed-up the VCS actions.

@item ClearCase module
@cindex ClearCase module
Whether the built-in ClearCase (see @ref{Version Control System})
module is activated or disabled.

@item Default VCS
@cindex Default VCS
The default VCS to use when the project does not define a VCS.

@end table

@item @b{Visual diff}
@cindex visual diff
@cindex file comparison

Note that in order to perform visual comparison between files, GPS
needs to call external tool (not distributed with GPS) such as @command{diff}
or @command{patch}. These tools are usually found on most unix systems, and
may not be available by default on other OSes. Under Windows, you can
download them from one of the unix toolsets
available, such as msys (@url{http://www.mingw.org}) or
cygwin (@url{http://www.cygwin.com}).

@table @i

@item mode
@cindex diff
How GPS displays visual diffs between two files:

@table @b
@item Side_By_Side
Editors are displayed side-by-side; new editors are created as needed

@item Unified
No new editor is created, and changes are displayed directly in the reference
editor.

@end table

@item Diff command
@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.
This command is used internally by GPS to perform the visual comparison on
versioned files (e.g. when performing a comparison with a version control
system).

This command should be compatible with the @command{GNU patch} utility.

@item Use old diff
@cindex old diff
Use the old version of the visual comparison.

@item Diff3 command
@cindex diff3
This item is only displayed if the preference @i{Use old diff} is disabled.
Command used to query a 3-way diff. See @i{Diff command} for a description
of the parameters.

@item Default color
This item is only displayed if the preference @i{Use old diff} is disabled.
The color used to indicate lines on which there is a difference, in the
"reference" editor.

@item Old color
This item is only displayed if the preference @i{Use old diff} is disabled.
The color used to indicate spaces used by lines not present in one of the
editors in a 3-way diff and present in the other editors.

@item Append color
This item is only displayed if the preference @i{Use old diff} is disabled.
The color used to display the lines that are present in an editor but not in the
reference editor.

@item Remove color
This item is only displayed if the preference @i{Use old diff} is disabled.
The color used to display the lines that are present in the reference editor
but not in other editors.

@item Change color
This item is only displayed if the preference @i{Use old diff} is disabled.
The color used to display the lines that have changed between the reference
editor and the other editors.

@item Fine change color
This item is only displayed if the preference @i{Use old diff} is disabled.
The color used to highlight fine differences within a modified line.

@item Context length
@cindex context length
This item is only displayed if the preference @i{Use old diff} is enabled.
The number of lines displayed before and after each chunk of differences.
Specifying -1 will display the whole file.

@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 File pattern
@cindex file pattern
@cindex location
Pattern used to detect file locations and the type of the output from the
messages window.
This is particularly useful when using an external tool such as a compiler
or a search tool, so that GPS will highlight and allow navigation through source
locations. This is a standard system V regular expression containing from two
to five parenthesized subexpressions corresponding to the file, line, column,
warnings or style error patterns.

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

@item Warning index
@cindex warning index
Index of the warning identifier in the file pattern.

@item Style index
@cindex column index
Index of the style error identifier in the file pattern.

@end table

@item @b{Project}
@table @i

@item Relative project paths
@cindex relative project path
Whether paths should be absolute or relative when the projects are modified.

@item Fast Project Loading
@cindex fast project loading
If the project respects a number of restrictions, activating the preference
will provide major speed up when GPS parses the project. This is especially
noticeable if the source files are on a network drive.

GPS assumes that the following restricitions are true when the preference
is activated. If this isn't the case, no error is reported, and only minor
drawacks will be visible in GPS (no detection that two files are the same
if one of them is a symbolic link for instance, although GPS will still
warn you if you are trying to overwrite a file modified on the disk).

The restrictions are the following:
@itemize -
@item Symbolic links shouldn't be used in the project.
  More precisely, you can only have symbolic links that point to files
  outside of the project, but not to another file in the project

@item Directories can't have source names.
  No directory name should match the naming scheme defined in the
  project. For instance, if you are using the default GNAT naming scheme,
  you cannot have directories with names ending with ".ads" or ".adb"

@end itemize

@item Load Xref info on project load
@cindex load xref info on project load
Whether the Xref information should be automatically loaded into memory when
a new project is loaded. @xref{Support for Cross-References}.

@item Hidden directories pattern
@cindex hidden directories pattern
A regular expression used to match hidden directories. Such directories
are not displayed by default in the project view, and are not taken into
account for VCS operations working on directories.

@end table

@item @b{Outline}
@anchor{Outline Preferences}

@table @i
@item Font

You can choose a specific font for the outline view. Typically, this will
be used to use a slightly smaller font than in the editor, so that you can
see more entities at once on the screen.

@item Show Profiles

For some of the languages, in particular Ada, GPS can display the profile
(list of parameters) for the subprograms. This can be used to differentiate
between overloaded entities (ie entities with the same name). Disabling
this preference will only show the entity name.

@item Sort alphabetically

If this preference is activated, the entities will be sorted alphabetically
in the outline view. If disabled, they will be displayed in the order they are
found in the source file.

@item Link with Editor

If this option is set, the current subprogram will be selected in the outline
view every time the cursor position changes in the current editor. This
option requires some computation for GPS, and you might want to avoid the
slow down by disabling it.

@item Show file name

If this option is set, the outline view will show the name of the file on its
first line, and indent slightly all following lines. If this option is unset,
this will save some screen real estate, but you will have to look at the
current editor to see what file is descrived in the Outline View.

@end table

@item @b{Documentation}
@anchor{Documention Preferences}

This section specifies preferences that apply to the
@i{Documentation Generator}. @ref{Documentation Generation} for more
information.

@table @i
@item Process body files

If this preference is enabled, implementation files will be processed.
Otherwise, only the specification files will.

@item Show private entities

By default, no documentation is generated for private entities.
Enabling this preference will change this behavior.

@item Call graph

If enabled, the documentation tool will compute and take advantage of source
references to e.g generate call graph information.
Activating this option will slow down the documentation generation process.

@item Up-to-date files only

If enabled, only files having up-to-date cross references information will be
documented.

@item Comments filter regexp

A regular expression used to filter to comments found in the source code before
using them for generating documentation. For example "^!.*" will remove all
comments starting with '!'.

@item Spawn a browser

If enabled, a browser is spawned after each documentation generation to view
the generated files. This browser is not spawned if disabled.

@item Find xrefs in comments

If enabled, GPS will try to find references to entities in comments, and
 generate links to them when generating the documentation.

@end table

@item @b{Coverage Analysis}
@anchor{Coverage Analysis Preferences}

@table @i

@item Coverage toolchain

Select which coverage toolchain (@code{gcov} or @code{xcov}) to use from
the @code{Tools->Coverage} menu.

@end table

@end itemize

@c -----------------------------------------------------------------
@node GPS Themes
@section GPS Themes
@cindex themes
@c -----------------------------------------------------------------

@noindent
GPS provides an extensive support for themes. Themes are predefined set
of value for the preferences, for the key bindings, or any other
configurable aspect of GPS.

For instance, color themes are a convenient way to change all colors in
GPS at once, according to predefined choices (strongly contrasted colors,
monochrome,...). It is also possible to have key themes, defining a set
of key bindings to emulate e.g. other editors.

Any number of themes can be activated at the same time through the
preferences dialog (@code{Edit->Preferences}). This dialog contains a list
of all themes that GPS knows about, organized into categories for convenient
handling. Just click on the buttons on the left of each theme name to activate
that theme.

Note that this will immediately change the current preferences settings. For
instance, if the theme you just selected changes the colors in the editor,
these are changed immediately in the @code{Editor->Fonts & Colors}. You can
of course still press @code{Cancel} to keep your previous settings

If multiple themes are active at the same time and try to override the same
preferences, the last theme which is loaded by GPS will override all previously
loaded themes. However, there is no predefined order in which the themes are
loaded.

@c -----------------------------------------------------------------
@node The Key Manager Dialog
@section The Key Manager Dialog
@c -----------------------------------------------------------------
@noindent

The key manager is accessible through the menu @code{Edit->Key Shortcuts}.
This dialog provides an easy way to associate key shortcuts with actions.
These actions are either predefined in GPS, or defined in your own
customization files, as documented in @ref{Customizing through XML and Python files}.
It also provides an easy way to redefine the menu shortcuts.

@iftex
@cindex screen shot
@image{key-shortcuts, 8.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{key-shortcuts}
@end ifhtml

Actions are referenced by their name, and are grouped into categories. These
categories indicate when the action applies. For instance, the indentation
command only applies in source editors, whereas the command to change the
current window applies anywhere in GPS.
The categories can be explicitly specified when you created your own actions
through XML files (@pxref{Defining Actions}).

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

If you define complex shortcuts for menus, they will not appear next to
the menu name when you select it with the mouse. This is expected, and is
due to technical limitations in the graphical toolkit that GPS uses.

When you assign a new shortcut to an action, the following happens:

@itemize @bullet
@item All actions and menus currently associated with the same key will no
 longer be executed when the key is pressed.
@item All key shortcuts defined for this action are replaced by the new one.
 As a result, the action is only executable through this new shortcut.
@end itemize

@c -----------------------------------------------------------------
@node The Plug-ins Editor
@section The Plug-ins Editor
@cindex plug-ins
@c -----------------------------------------------------------------

@noindent
GPS can be extensively customized through external plug-ins. You can
write your own plug-ins (@pxref{Customization files and plugins}), but
GPS also comes with its own collection of plug-ins.

Some of them are loaded by default when GPS starts (for instance the
support for the CVS version management system or support for
highlighting in various programming languages); others are available
for any user but not loaded automatically by GPS, for instance an
Emacs emulation mode.

Among the plug-ins that are provided with GPS, you will find:
@itemize @bullet
@item Emacs emulation
  @cindex Emacs
  Several plug-ins emulate some of the functions provided by Emacs, such
  as the interactive search, manipulation of rectangles, navigation in
  the editor, and of course the usual Emacs key shortcuts

  This emacs mode used to be activated in the preferences dialog, on the
  Themes page, but you should now activate it by loading the @file{emacs.xml}
  plug-in.

@item Makefile support
  @cindex Makefile
  A plug-in is provided that parses a Makefile and creates menus for each of
  its possible targets, so that you can easily start a make command.

@item Cross-references enhancements
  Various plug-ins take advantage of GPS's cross-references information to
  create additional menus to navigate (for instance to jump to the primitive
  operations of Ada tagged types, to the body of Ada separate entities, @dots{})

@item Text manipulation
  Several plug-ins provide support for advanced text manipulation in the
  editors, for instance to be able to align a set of lines based on various
  criteria, or to manipulate a rectangular selection of text.
@end itemize

You can chose graphically which plug-ins should or should not be loaded
on startup. To do so, select the menu @code{/Tools/Plug-ins}.
This brings up a new window, containing two parts:

@itemize @bullet
@item On the left is the list of all known plug-ins.

As described in @xref{Customization files and plugins}, GPS will
search for candidates in various directories, and based on these
directories decide whether to automatically load the plug-in or not.

This list indicates the name of the plug-in, and whether it has been
loaded in this GPS session (when the toggle button is checked).

@item On the right are the details for the selected plug-in

This window is displayed as a notebook with two pages: on the first
one you will see the exact location of the plug-in, the reason why it
was loaded or not, and, more importantly, the source of the plug-in.
By convention, each plug-in starts with a general comment that
indicates the purpose of this plug-in, and some more detailed
documentation on its usage.

For those interested, this also contains the plug-in itself, so that
this can act as an example to create your own customization script.

Technically, the list of plug-in to load or not to load
are stored in the file
@file{HOME/.gps/startup.xml}.

If you have modified anything through this dialog (the list of plug-ins
to load or unload), you will
need to restart GPS. GPS cannot unload a module, since it can have too
many possible effects on GPS (adding menus, overriding key
shortcuts, @dots{}).

A dialog is displayed asking you whether you would like to exit GPS
now. This will properly save all your files.

@end itemize

@c -----------------------------------------------------------------
@node Customizing through XML and Python files
@section Customizing through XML and Python files
@cindex customization
@c -----------------------------------------------------------------

@menu
* Customization files and plugins::
* Defining Actions::
* Macro arguments::
* Filtering actions::
* Adding new menus::
* Adding contextual menus::
* Adding tool bar buttons::
* Binding actions to keys::
* Preferences support in custom files::
* Creating themes::
* Defining new search patterns::
* Adding support for new languages::
* Defining text aliases::
* Defining project attributes::
* Adding casing exceptions::
* Adding documentation::
* Adding stock icons::
@c * Defining a documentation format::
* Remote programming customization::
* Customizing build Targets and Models::
* Toolchains customization::
@end menu

@c -----------------------------------------------------------------------
@node Customization files and plugins
@subsection Customization files and plugins
@c -----------------------------------------------------------------------

@noindent
You can customize lots of capabilities in GPS using files that are
loaded by GPS at start up.

For example, you can add items in the menu and tool bars, as well as
defining new key bindings, new languages, new tools, @dots{};
Using Python as a programming language, you can also add brand new facilities
and integrate your own tools in the GPS platform.

These customization files are searched for at startup in several different
places. Depending on the location where they are found, these files will either
be automatically loaded by GPS (and thus can immediately modify things in GPS),
or will simply be made visible in the Plug-ins Editor
(@pxref{The Plug-ins Editor}).

These directories are searched for in the order given below. Any script loaded
latter can override setups done by previously loaded scripts. For instance,
they could override a key shortcut, remove a menu, redefining a GPS
action, @dots{}

In the directory names below, @file{INSTALL} is the name of the directory in
which you have installed GPS. @file{HOME} is the user's home directory, either
by default or as overriden by the @code{GPS_HOME} environment variable. If none
of these exist, GPS will use the @code{USERPROFILE} environment variable.

In all these directories, only the files with @file{.xml} or @file{.py}
extensions are taken into account. Other files are ignored, although for
compatibility with future versions of GPS it is recommended not to keep other
files in the same directory.

@itemize @bullet
@item Automatically loaded system wide modules

The @file{INSTALL/share/gps/plug-ins} directory should contain the files that
GPS will automatically load by default (unless overriden by the user through
the Plug-ins Editor). These plug-ins are visible to any user on the
system that uses the same GPS installation. This directory should be reserved
for critical plug-ins that almost every one should use.

@item Not automatically loaded system wide modules

The @file{INSTALL/share/gps/library} directory should contain the files that
GPS should show in the Plug-ins Editor, but not load automatically.
Typically, these would be files that add optional capabilities to GPS, for
instance an emacs emulation mode, or additional editor capabilities that a lot
of users would not generally use.

@item @code{GPS_CUSTOM_PATH}

This environment variable can be set before launching GPS. It should contain
a list of directories, separated by semicolons (';') on Windows systems and
colons (':') on Unix systems. All the files in these directories with the
appropriate extensions will be automatically loaded by default by GPS,
unless overriden by the user through the Plug-ins Editor.

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

@item Automatically loaded user directory

The directory @file{HOME/.gps/plug-ins} is searched last. Any script
found in there will be automatically loaded unless overriden in the
Plug-ins Editor.

This is a convenient way for users to create their own plug-ins, or
test them before they are made available to the whole system by
copying them to one of the other directories.

@end itemize

Any script loaded by GPS can contain customization for various aspects
of GPS, mixing aliases, new languages or menus, @dots{} in a single
file. This is a convenient way to distribute your plug-ins to other
users.

@subsubsection Python files

Although the format of the python plug-ins is free (as long as it can
be executed by Python), the following organization is suggested. These
plug-ins will be visible in the Plug-ins Editor, and therefore having
a common format makes it easier for users to understand the goal of the
plug-ins:

@itemize @bullet
@item Comment

  The first part of the script should be a general comment on the goal and
  usage of the script. This comment should use python's triple-quote
  convention, rather than start-of-line hash ('#') signs.

  The first line of the comment should be a one liner explaining the goal
  of the script. It is separated by a blank line from the rest of the
  comment.

  The rest of the comment is free-form.

@item Customization variables

  If your script can be configured by the user by changing some global
  variables, they should be listed in their own section, and fully
  documented. The user can then, through the /Tools/Plug-ins editor
  change the value of these variables

@item Implementation

  The implementation should be separated from the initial comment by a
  form-feed (control-L) character. The startup scripts editor will know
  not to display the rest of the script on the first page of the editor.

  Generally speaking, scripts should avoid executing code as soon as they
  are loaded. This gives a chance to the user to change the value of global
  variables or even override functions before the script is actually launched.

  The solution is to connect to the @code{"gps_started"} hook, as in

@smallexample
  ^L
  ###########################################################
  ## No user customization below this line
  ###########################################################

  import GPS

  def on_gps_started (hook_name):
     ... launch the script

  GPS.Hook ("gps_started").add (on_gps_started)
@end smallexample

@end itemize

@subsubsection XML files

XML files must be utf8-encoded by default. In addition, you can
specify any specific encoding through the standard @code{<?xml
encoding="..." ?>} declaration, as in the following example:

@smallexample
<?xml version="1.0" encoding="iso-8859-1"?>
<!--  general description -->
<submenu>
  <title>encoded text</title>
</submenu>
@end smallexample

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

@smallexample
<?xml version="1.0" ?>
<root_node>
   ...
</root_node>
@end smallexample

It is also recommended that the first line after the @code{<?xml?>} tag
contains a general comment describing the purpose and usage of the script.
This comment will be made visible in the Plug-ins editor.

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

@table @code
@item <action>
(@pxref{Defining Actions})
@item <key>
(@pxref{Binding actions to keys})
@item <submenu>
(@pxref{Adding new menus})
@item <pref>
 (@pxref{Preferences support in custom files})
@item <preference>
 (@pxref{Preferences support in custom files})
@item <alias>
(@pxref{Defining text aliases})
@item <language>
  (@pxref{Adding support for new languages})
@item <button>
  (@pxref{Adding tool bar buttons})
@item <entry>
  (@pxref{Adding tool bar buttons})
@item <vsearch-pattern>
  (@pxref{Defining new search patterns})
@item <tool>
  (@pxref{Adding support for new tools})
@item <filter>
  (@pxref{Filtering actions})
@item <contextual>
  (@pxref{Adding contextual menus})
@item <case_exceptions>
  (@pxref{Adding casing exceptions})
@item <documentation_file>
  (@pxref{Adding documentation})
@item <doc_path>
  (@pxref{Adding documentation})
@item <stock>
  (@pxref{Adding stock icons})
@item <project_attribute>
  (@pxref{Defining project attributes})
@c @item <docgen_backend>
@c   (@pxref{Defining a documentation format})
@item <remote_machine_descriptor>
  (@pxref{Defining a remote server})
@item <remote_path_config>
  (@pxref{Defining a remote path translation})
@item <remote_connection_config>
  (@pxref{Defining a remote connection tool})
@item <rsync_configuration>
  (@pxref{Configuring rsync usage})
@end table

@c -----------------------------------------------------------------------
@node Defining Actions
@subsection Defining Actions
@cindex action
@cindex <action>
@cindex <shell>
@cindex <external>
@cindex <filter>
@c -----------------------------------------------------------------------

@noindent
This facility distinguishes the actions from their associated menus or
key bindings. Actions can take several forms: external commands,
shell commands and predefined commands, as will be explained in more details
below.

The general form to define new actions is to use the @code{<action>} tag.
This tag accepts the following attributes:

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

@item output  (optional)
If specified, this attribute indicates where the output of the commands will
be sent by default. This can be overridden by each command, using the same
attribute for @code{<shell>} and @code{<external>} tags,
@xref{Redirecting the command output}.

@item show-command (optional, default true)
If specified, this attribute indicates whether the text of the command itself
should be displayed at the same location as its output. Neither will be
displayed if the output is hidden. The default is to show the command along
with its output.
This attribute can be overridden for each command.

@item show-task-manager (optional, default false)
This attribute indicates whether an entry should be created in the task
manager to show this command. Associated with this entry is the progress
bar indicator, so if you hide the entry, no progress will be shown. On the
other hand, several progress bars might be displayed for your action if you
show the progress bar here, which might be an issue depending on the
context.
This attribute can be overriden for each external command.

@item category (optional, default "General")
The category in the keybindings editor (menu @code{Edit/Key bindings}) in which
the action should be shown to the user. If you specify an empty string, the
action is considered as an implementation detail, and not displayed in the
editor. The user will thus not be able to assign it a keybinding through the
graphical user interface (although this is still doable through XML commands).
@end table

If you are defining the same action multiple times, the last definition will
be kept. However, existing menus, buttons, @dots{} that already reference that
action will keep their existing semantic. The new definition will only be
used for all new menus created from that point on.

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

The following XML tags are valid children for @code{<action>}.
@table @code

@cindex external
@item <external>
This defines a command to execute through the system (i.e. a standard Unix or
Windows command)

Note for Windows users: like under UNIX, scripts can be called
from custom menu. In order to do that, you need to write your script in a
@file{.bat} or @file{.cmd} file, and call this file as usual.
The @code{external} tag would e.g. look like:

@smallexample
<?xml version="1.0" ?>
<external_example>
  <action name="my_command">
    <external>c:\.gps\my_scripts\my_cmd.cmd</external>
  </action>
</external_example>
@end smallexample

This tag accepts the following attributes:

   @table @code
   @item server (optional)
   This attribute can be used to execute the external command on a remote
   server. The accepted values are @code{"gps_server"} (default),
   @code{"build_server"}, @code{"execution_server"}, @code{"debug_server"} and
   @code{"tools_server"}.
   @xref{Remote operations}, for explanation of what these servers are.

   @item check-password (optional)
   @cindex password
   This attribute can be used to tell GPS to check and handle password prompts
   from the external command. The accepted values are @code{"false"} (default)
   and @code{"true"}.

   @item show-command (optional)
   This attribute can be used to override the homonym attribute specified for
   the @code{<action>} tag.

   @item output (optional)
   This attribute can be used to override the homonym attribute specified for
   the @code{<action>} tag.

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

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

@smallexample
<?xml version="1.0" ?>
<progress_action>
  <action name="progress" >
    <external
      progress-regexp="(\d+) out of (\d+).*$"
      progress-current="1"
      progress-final="2"
      progress-hide="true">gnatmake foo.adb
    </external>
  </action>
</progress_action>
@end smallexample

   @item progress-current (optional, default is 1)
   This is the opening parenthesis count index in @code{progress-regexp}
   that contains the current step.

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

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

   @item show-task-manager (optional, default inherited from @code{<action>})
   This attribute indicates whether an entry should be created in the task
   manager to show this command. Associated with this entry is the progress
   bar indicator, so if you hide the entry, no progress will be shown. On the
   other hand, several progress bars might be displayed for your action if you
   show the progress bar here, which might be an issue depending on the
   context.

   If you have set a value for @code{progress-regexp}, this will automatically
   be set to true by default so that the progress bar is indeed displayed in
   the task manager. You can still override it explicitly for that
   @code{<external>} element to force hiding the progress bar.

   @end table

@cindex on-failure
@item <on-failure>

This tag specifies a group of command to be executed if the previous
external command fails. Typically, this is used to parse the output of the
command and fill the location window appropriately
(@pxref{Processing the tool output}).

For instance, the following action spawn an external tool, and parses its
output to the location window and the automatic fixing tool if the external
tool happens to fail.

In this group of commands the %... and $... macros can be used (@pxref{Macro arguments}).

@smallexample
<?xml version="1.0" ?>
<action_launch_to_location>
  <action name="launch tool to location" >
    <external>tool-path</external>
    <on-failure>
      <shell>Locations.parse "%1" category<shell>
      <external>echo the error message is "%2"</external>
    </on-failure>
    <external>echo the tool succeeded with message %1</external>
  </action>
</action_launch_to_location>
@end smallexample

@cindex shell
@cindex shell
@cindex interactive command
@item <shell>
As well as external commands, you can use custom menu items to invoke GPS
commands using the @code{shell} tag. These are command written in one of the
shell scripts supported by GPS.

This tag supports the same @code{show-command} and @code{output} attributes
as the @code{<action>} tag.

The following example shows how to
create two actions to invoke the @code{help} interactive command and to open
the file @file{main.c}.

@smallexample
<?xml version="1.0" ?>
<help>
  <action name="help">
    <shell>help</shell>
  </action>
  <action name="edit">
    <shell>edit main.c</shell>
  </action>
</help>
@end smallexample

By default, commands are expected to be written in the GPS shell language.
However, you can specify the language through the @code{lang} attribute. Its
default value is @code{"shell"}.

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.

@smallexample
<?xml version="1.0" ?>
<current_file_uses>
  <action name="current file uses">
    <shell lang="shell">File %f</shell>
    <shell lang="shell">File.uses %1</shell>
  </action>
</current_file_uses>
@end smallexample

@item <description>
@cindex description
This tag contains a description for the command, which is used in the
graphical editor for the key manager. @xref{The Key Manager Dialog}.

@item <filter>, <filter_and>, <filter_or>
@cindex filter
This is the context in which the action can be executed,
@xref{Filtering actions}.

@end table

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
<?xml version="1.0" ?>
<xterm_directory>
  <action "xterm in current directory">
    <shell lang="shell">cd %d</shell>
    <external>xterm</external>
  </action>
</xterm_directory>
@end smallexample

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

More information on chaining commands is provided in @xref{Chaining commands}.

Some actions are also predefined in GPS itself. This include for instance
aliases expansion, manipulating MDI windows, @dots{};
All known actions (predefined
and the ones you have defined in your own customization files) can be
discovered by opening the key shortcut editor (@code{Edit->Key shortcuts} menu).

@c ---------------------------------------------------------------------
@node Macro arguments
@subsection Macro arguments
@cindex menu
@cindex argument
@cindex substitution
@c ---------------------------------------------------------------------

@noindent
When an action is defined, you can use macro arguments to pass to your
shell or external commands. Macro arguments
are special parameters that are transformed every time the command is executed.
The following macro arguments are provided.

The equivalent python command is given for all tests. These commands are useful
when you are writing a full python script, and want to test for yourself
whether the context is properly defined.

@table @code
@item %a
If the user clicked within the Locations Window, this is the name of the
category to which the current line belongs

@item %builder
Replaced by the default builder configured in GPS.
This can be e.g. @code{gnatmake} if your project contains only Ada code,
or @code{gprbuild} for non Ada or multi-language projects, or @code{gprmake}
if you have set the multi language builder preference accordingly.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %c
This is the column number on which the user clicked.
Python equivalent:
@smallexample
GPS.current_context().column()
@end smallexample

@item %d
The current directory.
Python equivalent:
@smallexample
GPS.current_context().directory()
@end smallexample

@item %dk
The krunched name of the current directory.

@item %e
Name of the entity the user clicked on.
Python equivalent:
@smallexample
GPS.current_context().entity().name()
@end smallexample

@item %E
The full path to the executable name corresponding to the target.

@item %ek
Krunched name of the entity the user clicked on.
This is the same as @code{%e}, except long names are shorted as in @code{%fk}.

@item %eL
Replaced by either an empty string, or @code{-eL}, depending on whether the
@code{Fast Project Loading} preference if set or not.
@code{-eL} is used by GNAT tools to specify whether symbolink links
should be followed or not when parsing projects.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %external
Replaced by the command line specified in the preference
  @i{External Commands->Execute command}.

@item %f
Base name of the currently selected file.
Python equivalent:
@smallexample
import os.path
os.path.basename (GPS.current_context().file().name())
@end smallexample

@item %F
Absolute name of the currently opened file.
Python equivalent:
@smallexample
GPS.current_context().file().name()
@end smallexample

@item %fk
Krunched base name of the currently selected file.
This is the same as %f, except that long names are shortened, and their middle
letters are replaced by "[...]". This should be used in particular in menu
labels, to keep the menus narrow.

@item %fp
Base name of the currently selected file. If the file is not part of the project
tree, or no file is selected, generate an error on the Messages window.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %gnatmake
Replaced by the gnatmake executable configured in your project file.

@item %gprbuild
Replaced by the gprbuild or gprmake command line configured in your project
file.

@item %gprclean
Replaced by the default cleaner configured in GPS.
This can be e.g. @code{gnat clean}, or @code{gprclean}.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %i
If the user clicked within the Project View, this is the name of the parent
project, ie the one that is importing the one the user clicked on. Note that
with this definition of parent project, a given project might have multiple
parents. The one that is returned is read from the Project View itself.

@item %l
This is the line number on which the user clicked.
Python equivalent:
@smallexample
GPS.current_context().line()
@end smallexample

@item %o
The object directory of the current project.

@item %O
The object directory of the root project.

@item %p
The current project. This is the name of the project, not the project file, ie
the @file{.gpr} extension is not included in this name, and the casing is the
one found inside the project file, not the one of the file name itself.
If the current context is an editor, this is the name of the project to which
the source file belongs.
Python equivalent:
@smallexample
GPS.current_context().project().name()
@end smallexample

@item %P
The root project. This is the name of the project, not the project file.
Python equivalent:
@smallexample
GPS.Project.root().name()
@end smallexample

@item %Pb
The basename of the root project file.

@item %Pl
The name of the root project, all lower case.

@item %pp
The current project file pathname. If a file is selected, this is the project
file to which the source file belongs.
Python equivalent:
@smallexample
GPS.current_context().project().file().name()
@end smallexample

@item %PP
The root project pathname.
Python equivalent:
@smallexample
GPS.Project.root().file().name()
@end smallexample

@item %pps
This is similar to @code{%pp}, except it returns the project name prepended
with @code{-P}, or an empty string if there is no project file selected and the
current source file doesn't belong to any project. This is mostly for use with
the GNAT command line tools. The project name is quoted if it contains spaces.
Python equivalent:
@smallexample
if GPS.current_context().project():
   return "-P" & GPS.current_context().project().file().name()
@end smallexample

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

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

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

Python equivalent:
@smallexample
GPS.current_context().project().source_dirs()
@end smallexample

@item s
list the source files.

Python equivalent:
@smallexample
GPS.current_context().project().sources()
@end smallexample

@item f
output the list into a file and substitute the parameter with the
name of that file. This file is never deleted by GPS, it is your responsibility
to do so.
@end table

@item %s
This is the text selected by the user, if a single line was selected. When
multiple lines were selected, this returns the empty string

@item %S
This is either the text selected by the user, of the current entity if there
is no selection. If the entity is part of an expression ("A.B.C"), then the
whole expression is used instead of the entity name.

@item %switches(tool)
Replaced by @code{IDE'Default_Switches (tool)}, in other words, if you
have a tool whose switches are defined via an xml file in GPS, they
are stored as @code{Default_Switches (xxx)} in the @code{IDE} package
and can be retrieved using this macro. The value returned is a list of
switches, or an empty list if not set.

Note: This macro is only available in the commands defined in the Build
Manager and Build Launcher dialogs.

@item %T
Replaced by the subtarget being considered for building.
Depending on the context, this can correspond to e.g. the base filename of a
Main source, or makefile targets.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %TT
Same as @code{%TT}, but returns the full path to main sources rather than
the base filename.

@item %attr(Package'Name[,default])
Replaced by the project attribute @code{Package'Name}, in other words, the
attribute @code{Name} from the package @code{Package}. @code{Package'} is
optional if @code{Name} is a top level attribute (e.g. @code{Object_Dir}).

If the attribute is not defined in the project, an optional @code{default}
value is returned, or an empty string if not.

Note: This macro is only available in the commands defined in the Build
Manager and Build Launcher dialogs, and only supports single string attributes,
not lists.

@item %dirattr(Package'Name[,default])
Replaced by the directory part of an attribute. The attribute is specified
as in @code{%attr} above.

@item %baseattr(Package'Name[,default])
Replaced by the base name of an attribute. The attribute is specified
as in @code{%attr} above.

@item %vars
Replaced by a list of switches of the form @code{<variable>=<value>}, where
<variable> is the name of a scenario variable and <value> its current
value, as configured in the Scenario View. All the scenario variables
defined in the current project tree will be listed.
Alternatively, you can also use @code{%vars(-D)} to generate a list of
switches of the form @code{-D<variable>=<value>}.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %X
Replaced by a list of switches of the form @code{-X<variable>=<value>}, where
<variable> is the name of a scenario variable and <value> its current
value, as configured in the Scenario View. All the scenario variables
defined in the current project tree will be listed.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

@item %%
Replaced by the % sign.
@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

Another type of macros are expanded before commands are executed: These
all start with the @code{$} character, and represent parameters passed to
the action by its caller. Depending on the context, GPS will give zero, one
or more arguments to the action. This is in particular used when you define
your own VCS system. See also the shell function @code{execute_action}, which
you can use yourself to execute an action and pass it some arguments.

These arguments are the following
@table @code
@item $1, $2, ... $n
Where n is a number. These are each argument passed to the action

@item $1-, $2-, ... $n-
This represents a string concatenating the specified argument and all
arguments after it

@item $*
This represents a string concatenating all arguments passed to the action

@item $repeat
This is the number of times the action has been repeated in a row. It will in
general be 1 (ie this is the first execution of the action), unless the user
has first executed the action @code{"Repeat Next"}, which allows automatic
repetition of an action.

By default, when the action "Repeat Next" is invoked by the user, it will repeat
the following action as many times as the user specified. However, in some cases,
either for efficiency reasons or simply for technical reasons, you might want to
handle yourself the repear. This can be done with the following action
declaration:

@smallexample
<action name="my_action">
   <shell lang="python">if $repeat==1: my_function($remaining + 1)</shell>
</action>

def my_function (count):
   """Perform an action count times"""
   ...
@end smallexample

Basically, the technics here is to only perform something the first time the
action is called (hence the if statement), but pass your shell function the
number of times that it should repeat (hence the @code{$remaining} parameter).

@item $remaining
This is similar to $repeat, and indicates the number of times that the action
remains to be executed. This will generally be 0, unless the user has chosen
to automatically repeat the action a number of times.

@end table

@c ----------------------------------------------------------------------
@node Filtering actions
@subsection Filtering actions
@cindex <filter>
@cindex <filter_and>
@cindex <filter_or>
@c ----------------------------------------------------------------------

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

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

Actions can be restricted in several ways:

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

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

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

Note however that the current context might contain more information than you
expect. For instance, if you click on a file name in the Project View, then
the current context contains a file (thus satisfies @code{%F}), but also
contains a project (and thus satisfies @code{%p} and similar macros).

@item Defining explicit filters
Explicit restrictions can be specified in the customization files. These are
specified through the @code{<filter>}, @code{<filter_and>}
and @code{<filter_or>} tags, see below.

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

@end enumerate

@subsubsection The filters tags

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

@enumerate
@item At the toplevel.
At the same level as other tags such as @code{<action>}, @code{<menu>} or
@code{<button>} tags, you can define named filters. These are general filters,
that can be referenced elsewhere without requiring code duplication.

@item As a child of the @code{<action>} tag.
Such filters are anonymous, although they provide exactly the same capabilities
as the ones above. These are mostly meant for simple filters, or filters that
you use only once.
@end enumerate

There are three different kinds of tags:

@table @code
@item <filter>
This defines a simple filter. This tag takes no child tag.

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

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

@end table

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

The @code{<filter>}, @code{<filter_and>} and @code{<filter_or>} tags accept the
following set of common attributes:

@table @code
@item name       (optional)
This attribute is used to create named filters, that can be reused elsewhere
in actions or compound filters through the @code{id} attribute. The name can
take any form.

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

@end table

In addition, the @code{<filter>} has the following specific attributes:

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

@smallexample
<?xml version="1.0" ?>
<test_filter>
  <filter name="Test filter" language="ada" />
  <action name="Test action" >
     <filter id="Test filter" />
     <shell>pwd</shell>
  </action>
</test_filter>
@end smallexample

  A number of filters are predefined by GPS itself.

  @table @code
  @item Source editor
  This filter will only match if the currently selected window in GPS is an
  editor.
  @item Explorer_Project_Node
  Matches when clicking on a project node in the Project View
  @item Explorer_Directory_Node
  Matches when clicking on a directory node in the Project View
  @item Explorer_File_Node
  Matches when clicking on a file node in the Project View
  @item Explorer_Entity_Node
  Matches when clicking on an entity node in the Project View
  @item File
  Matches when the current context contains a file (for instance the focus is
   on a source editor, or the focus is on the Project view and the currently
   selected line contains file information).
  @end table

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

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

Macro arguments (%f, %p, @dots{}) are fully supported in the text of the
command to execute.

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

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

The list of module names can be obtained by typing @code{lsmod} in the shell
console at the bottom of the GPS window.

This attribute is mostly useful when creating new contextual menus.

@end table

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

@smallexample
<?xml version="1.0" ?>
<!-- The following filter will only match if the currently selected
     window is a text editor editing an Ada source file -->
<ada_editor>
  <filter_and name="Source editor in Ada" >
    <filter language="ada" />
    <filter id="Source editor" />
  </filter_and>

  <!-- The following action will only be executed for such an editor -->

  <action name="Test Ada action" >
     <filter id="Source editor in Ada" />
     <shell>pwd</shell>
  </action>

  <!--  An action with an anonymous filter. It will be executed if the
        selected file is in Ada, even if the file was selected through
        the project view  -->

  <action name="Test for Ada files" >
      <filter language="ada" />
      <shell>pwd</shell>
  </action>
</ada_editor>
@end smallexample

@c ----------------------------------------------------------------------
@node Adding new menus
@subsection Adding new menus
@cindex menus
@cindex <menu>
@cindex <submenu>
@cindex <title>
@c ----------------------------------------------------------------------

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

Binding a menu to an action is done through the @code{<menu>} and
@code{<submenu>} tags.

The @code{<menu>} tag takes the following attributes:

@table @code
@item action  (mandatory)
This attribute specifies which action to execute
when the menu is selected by the user. If no action by this name was defined,
no new menu is added. The action name can start with a '/', in which case
it represents the absolute path to a menu to execute instead.

This attribute can be omitted only when no title is specified for the menu
to make it a separator (see below).

If a filter is associated with the action through the @code{<filter>} tag,
then the menu will be greyed out when the filter doesn't match. As a
result, users will not be able to click on it.

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

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

@end table

It should also have one XML child called @code{<title>} which specifies the
label of the menu. This is really a path to a menu, and thus you can define
submenus by specifying something like "/Parent1/Parent2/Menu" in the title
to automatically create the parent menus if they don't exist yet.

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

The tag @code{<submenu>} accepts the following attributes:

@table @code
@item before  (optional)
See description above, same as for @code{<menu>}

@item after   (optional)
See description above, same as for @code{<menu>}
@end table

It accepts several children, among @code{<title>} (which must be specified
at most once), @code{<submenu>} (for nested menus), and @code{<menu>}.

Since @code{<submenu>} doesn't accept the @code{action} attribute, you should
use @code{<menu>} for clickable items that should result in an action, and
@code{<submenu>} if you want to define several menus with the same path.

You can specify which menu the new item is added to in one of two ways:

@itemize @bullet
@item Specify a path in the @code{title} attribute of @code{<menu>}
@item Put the @code{<menu>} as a child of a @code{<submenu>} node
  This requires slightly more typing, but it allows you to specify the exact
  location, at each level, of the parent menu (before or after an existing
  menu).
@end itemize

For example, this adds an item named @code{mymenu} to the standard
@code{Edit} menu.

@smallexample
<?xml version="1.0" ?>
<test>
  <submenu>
    <title>Edit</title>
    <menu action="current file uses">
       <title>mymenu</title>
    </menu>
  </submenu>
</test>
@end smallexample

The following has exactly the same effect:

@smallexample
<?xml version="1.0" ?>
<test>
  <menu action="current file uses">
    <title>Edit/mymenu</title>
  </menu>
</test>
@end smallexample

The following adds a new item "stats" to the "unit testing" submenu
in "my_tools".

@smallexample
<?xml version="1.0" ?>
<test>
  <menu action="execute my stats">
     <title>/My_Tools/unit testing/stats</title>
  </menu>
</test>
@end smallexample

The previous syntax is shorter, but less flexible than the following,
where we also force the My_Tools menu, if it doesn't exist yet, to
appear after the File menu. This is not doable by using only @code{<menu>}
tags. We also insert several items in that new menu

@smallexample
<?xml version="1.0" ?>
<test>
  <submenu after="File">
    <title>My_Tools</title>
    <menu action="execute my stats">
       <title>unit testing/stats</title>
    </menu>
    <menu action="execute my stats2">
       <title>unit testing/stats2</title>
    </menu>
  </submenu>
</test>
@end smallexample

@cindex menu separator
Adding an item with an empty title or no title at all inserts a
menu separator. For instance, the following example will insert a separator
followed by a File/Custom menu:

@smallexample
<?xml version="1.0" ?>
<menus>
  <action name="execute my stats" />
  <submenu>
     <title>File</title>
     <menu><title/></menu>
     <menu action="execute my stats">
         <title>Custom</title>
     </menu>
  </submenu>
</menus>
@end smallexample

@c ----------------------------------------------------------------------
@node Adding contextual menus
@subsection Adding contextual menus
@cindex <contextual>
@c ----------------------------------------------------------------------

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

Such contributions are done through the @code{<contextual>} tag, which takes
the following attributes:

@table @code
@item "action"  (mandatory)
Name of the action to execute, and must be defined elsewhere in one of the
customization files.

If this attribute is set to an empty string, a separator will be inserted
in the contextual menu instead. If you specify a reference item with one of
the "before" or "after" attribute, the separator will be visible only when
the reference item is visible.

@item "before" (optional, default="")
If it is specified, this attribute should be the name of another contextual,
before which the new menu should appear. The name of predefined contextual
menus can be found by looking at the output of "Contextual.list" in the shell
console. The name of the contextual menus you define yourself is the value of
the @code{<title>} child.

There is no guarantee that the new menu will appear just before the referenced
menu. In particular, it won't be the case if the new menu is created before
the reference menu was created, or if another later contextual menu indicates
that it must be displayed before the same reference item.

@item "after" (optional, default="")
Same as "before", except it indicates the new menu should appear after the
reference item.

If both "after" and "before" are specified, only the latter is taken into
account.

@end table

It accepts one child tag, @code{<Title>} which specifies the name of the
menu entry. If this child is not specified, the menu entry will use the name
of the action itself. The title is in fact the full path to the new menu entry.
Therefore, you can create submenus by using a title of the form
"Parent1/Parent2/Menu".

Special characters can be used in the title, and will be automatically
expended based on the current context. These are exactly the ones described
in the section for macros arguments, @xref{Macro arguments}.

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

For instance, the following example inserts a new contextual menu which prints
the name of the current file in the GPS console. This contextual menu is only
displayed in source editors. This contextual menu entry is followed by a
separator line, visible when the menu is visible

@smallexample
<?xml version="1.0" ?>
<print>
  <action name="print current file name" >
    <filter module="Source_Editor" />
    <shell>echo %f</shell>
  </action>

  <contextual action="print current file name" >
    <Title>Print Current File Name</Title>
  </contextual>
  <contextual action="" after="Print Current File Name" />
</print>
@end smallexample

@c ----------------------------------------------------------------------
@node Adding tool bar buttons
@subsection Adding tool bar buttons
@cindex tool bar
@cindex <button>
@cindex <entry>
@c ----------------------------------------------------------------------

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

@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{<button>} tag indicates a separator in the tool bar.

A title can also be specified with @code{<title>}. This will be visible only
if the user choses to see both text and icons (or text only) in the tool bar.
This title also acts as a tooltip (popup help message) when the button is
displayed as an icon only.

The following example defines a new button:

@smallexample
<?xml version="1.0" ?>
<stats>
  <button action="execute my stats">
    <title>stats</title>
    <pixmap>/my_pixmaps/button.jpg</pixmap>
  </button>
</stats>
@end smallexample

The @code{<button>} tag allows you to create a simple button that the user
can press to start an action. GPS also supports another type of button,
a combo box, from which the user can choose among a list of choices. Such
a combo box can be created with the @code{<entry>} tag.

This tag accepts the following arguments:

@table @code
@item id (mandatory)

This should be a unique id for this combo box, and will be used later on
to refer it, in particular from the scripting languages. It can be any
string

@item label (default is "")

The text of a label to display on the left of the combo box. If this isn't
specified, no text will be displayed

@item on-changed (default is "")

The name of a GPS action to execute whenever the user selects a new value
in the combo box. This action is called with two parameters, the unique id
of the combo box and the newly selected text respectively.
@end table

It also accepts any number of @code{<choice>} tags, each of which defines
one of the values the user can choose from. These tags accepts one optional
attribute, "on-selected", which is the name of a GPS action to call when
that particular value is selected.

@smallexample
   <action name="animal_changed">
      <shell>echo A new animal was selected in combo $1: animal is $2</shell>
   </action>
   <action name="gnu-selected">
      <shell>echo Congratulations on choosing a Gnu</shell>
   </action>
   <entry id="foo" label="Animal" on-changed="animal_changed">
      <choice>Elephant</choice>
      <choice on-selected="gnu-selected">Gnu</choice>
   </entry>
@end smallexample

A more convenient interface exists for Python, the GPS.Toolbar class, which
gives you the same flexibility as above, but also gives you dynamic control
over the entry, and allows placement of buttons at arbitrary positions in
the toolbar. See the python documentation.

@c ---------------------------------------------------------------------
@node Binding actions to keys
@subsection Binding actions to keys
@cindex key
@cindex <key>
@c ----------------------------------------------------------------------

@noindent
All the actions defined above can be bound to specific key shortcuts through
the @code{<key>} attribute. As usual, it requires one @code{<action>}
attribute to specify what to do when the key is pressed. The name of the
action can start with a '/' to indicate that a menu should be executed
instead of a user-defined action.

If the action is the empty string, then instead the key will no longer be
bound to any action.

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

You can also define multiple key bindings similar to Emacs's by separating them
by a space. For instance, @code{control-x control-k} means that the user should
press @key{control-x}, followed by a @key{control-k} to activate the
corresponding action. This is only possible if the prefix key is not already
bound to an action. If it is, you should first unbound it by passing an
empty action to @code{<key>}.

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

@smallexample
<?xml version="1.0" ?>
<keys>
  <key action="expand alias">control-o</key>
  <key action="Jump to matching delimiter" />

  <!--  Bind a key to a menu -->
  <key action="/Window/Close">control-x control-w</key>
</key>
@end smallexample

Multiple actions can be bound to the same key binding. They will all be
executed in turn, followed by any menu for which this key is an accelerator.

When GPS processes a @code{<key>} tag, it does the following:
@itemize @bullet
@item Removes all actions bound to that key.
   This ensures that if you press the key, any action associated with it by
   default in GPS or in some other XML file will no longer be executed, and
   only the last one will be executed.
@item Adds the new key to the list of shortcuts that can execute the
   action. Any existing shortcut on the action is preserved, and
   therefore there are multiple possible shortcuts for this action.
@end itemize

@c ----------------------------------------------------------------
@node Preferences support in custom files
@subsection Preferences support in custom files
@c ----------------------------------------------------------------

@subsubsection Creating new preferences
@cindex <preference>

@noindent
GPS has a number of predefined preferences to configure its behavior and its
appearance. They are all customizable through the Edit->Preferences menu.

However, you might wish to add your own kind of preferences for your extension
modules. This can easily be done through the usual GPS customization files.
Preferences are different from project attributes (@pxref{Defining project attributes}),
in that the latter will vary depending on which project is loaded
by the user, whereas preferences are always set to the same value no matter
what project is loaded.

Such preferences are created with the @code{<preference>} tag, which takes
a number of attributes.

@table @code
@item name (mandatory)

This is the name of the preference, used when the preference is saved by
GPS in the @file{$HOME/.gps/preferences} file, and to query the value of
a preference interactively through the @code{GPS.Preference} class in the
GPS shell or python. There are a few limitation to the form of these names:
they cannot contain space or underscore characters. You should replace the
latter with minus signs for instance.

@item page (optional, default is "General")

The name of the page in the preferences editor where the preference can
be edited. If this is the name of a non-existing page, GPS will automatically
create it. If this is the empty string (""), the preference will not be
editable interactively. This could be used to save a value from one session
of GPS to the next, without allowing the user to alter it.

Subpages are references by separating pages name with colons (':').

@item default (optional, default depends on the type of the preference)

The default value of the preference, when not set by the user. This is 0 for
integer preferences, the empty string for string preferences, True for boolean
values, and the first possible choice for choice preferences.

@item tip (optional, default is "")

This is the text of the tooltip that appears in the preferences editor
dialog.

@item label (mandatory)

This is the name of the preference as it appears in the preferences editor
dialog

@item type (mandatory)

This is the type of the preference, and should be one of:

@itemize
@item "boolean"

The preference can be True or False.

@item "integer"

The preference is an integer. Two optional attributes can be specified for
@code{<preference>}, "minimum" and "maximum", which define the range of
valid values for that integer. Default values are 0 and 10 respectively.

@item "string"

The preference is a string, which might contain any value

@item "color"

The preference is a color name, in the format of a named color such as
"yellow", or a string similar to "#RRGGBB", where RR is the red component,
GG is the green component, and BB is the blue component

@item "font"

The preference is a font

@item "choices"

The preference is a string, whose value is chosen among a static list of
possible values. Each possible value is defined in a @code{<choice>} child
of the @code{<preference>} node.

@end itemize

@end table

Here is an example that defines a few new preferences:

@smallexample
<?xml version="1.0"?>
<custom>
   <preference name="my-int"
               page="Editor"
               label="My Integer"
               default="30"
               minimum="20"
               maximum="35"
               page="Manu"
               type="integer" />

   <preference name="my-enum"
               page="Editor:Fonts &amp; Colors"
               label="My Enum"
               default="1"
               type="choices" >
     <choice>Choice1</choice>
     <choice>Choice2</choice>  <!--  The default choice -->
     <choice>Choice3</choice>
   </preference>
</custom>
@end smallexample

The values of the above preferences can be queries in the scripting languages:

@itemize

@item GPS shell

@smallexample
Preference "my-enum"
Preference.get %1
@end smallexample

@item Python

@smallexample
val = GPS.Preference ("my-enum").get ()
val2 = GPS.Preference ("my-int").get ()
@end smallexample

@end itemize

@subsubsection Setting preferences values
@cindex <pref>

@noindent
You can force specific default values for the preferences in the customization
files through the @code{<pref>} tag. This is the same tag that is used by
GPS itself when it saves the preferences edited through the preferences
dialog.

This tag requires on attribute:

@table @code
@item name
This is the name of the preference of which you are setting a default value.
Such names are predefined when the preference is registered in GPS, and can
be found by looking at the @file{$HOME/.gps/preferences} file for each user,
or by looking at one of the predefined GPS themes.
@end table

It accepts no child tag, but the value of the @code{<pref>} tag defines the
default value of the preference, which will be used unless the user has
overridden it in his own preferences file.

Any setting that you have defined in the customization files will be
overridden by the user's preferences file itself, unless the user was still
using the default value of that preference.

This @code{<pref>} tag is mostly intended for use through the themes
(@pxref{Creating themes}).

@c ----------------------------------------------------------------
@node Creating themes
@subsection Creating themes
@cindex themes creation
@cindex <theme>
@c ----------------------------------------------------------------

@noindent
You can create your own themes and share them between users. You can then
selectively chose which themes they want to activate through the preferences
dialog (@pxref{GPS Themes}).

Creating new themes is done in the customization files through
the @code{<theme>} tag.

This tag accepts a number of attributes:

@table @code
@item name (mandatory)
This is the name of the theme, as it will appear in the preferences dialog

@item description (optional)
This text should explain what the text does. It appears in the preferences
dialog when the user selects that theme.

@item category (optional, default is General)
This is the name of the category in which the theme should be presented in
the preferences dialog. Categories are currently only used to organize themes
graphically. New categories are created automatically if you chose one that
doesn't exist yet.

@end table

This tag accepts any other customization tag that can be put in the
customization files. This includes setting preferences (@code{<pref>},
defining key bindings (@code{<key}), defining menus (@code{<menu>}), @dots{}

If the same theme is defined in multiple locations (multiple times in the
same customization file or in different files), their effects will be
cumulated. The first definition of the theme seen by GPS will set the
description and category for this theme.

All the children tags of the theme will be executed when the theme is activated
through the preferences dialog. Although there is no strict ordering in which
order the children will be executed, the global order is the same as for the
customization files themselves: first the predefined themes of GPS, then the
ones defined in customization files found through the @code{GPS_CUSTOM_PATH}
directories, and finally the ones defined in files found in the user's
own GPS directory.

@smallexample
<?xml version="1.0" ?>
<my-plug-in>
   <theme name="my theme" description="Create a new menu">
       <menu action="my action"><title>/Edit/My Theme Menu</title></menu>
   </theme>
</my-plug-in>
@end smallexample

@c ----------------------------------------------------------------
@node Defining new search patterns
@subsection Defining new search patterns
@cindex <vsearch-pattern>
@cindex predefined patterns
@c ----------------------------------------------------------------

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

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

@table @code
@item <name>

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

@item <regexp>

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

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

@item <string>

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

The tag accepts the same optional attribute @code{case-sensitive} as
above
@end table

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

@smallexample
<?xml version="1.0" ?>
<search>
  <vsearch-pattern>
    <name>Ada: assignment</name>
    <regexp case-sensitive="false">\b(\w+)\s*:=</regexp>
  </vsearch-pattern>
</search>
@end smallexample

@c --------------------------------------------------------------------------
@node Adding support for new languages
@subsection Adding support for new languages
@cindex <Language>
@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 view), find files
associated with a given language, @dots{}

As described previously for menu items, any file in the @file{plug-ins}
directory will be loaded by GPS at start up. Therefore, you can either
define new languages in a separate file, or reuse a file where you already
define actions and menus.

The following tags are available in a @code{Language} section:

@table @code
@item Name
A short string describing the name of the language.

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

@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, and consider using the @code{Extension} tag instead.
This tag must be unique.

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

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

@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. If the regular expression needs to match
characters other than letters and underscore, you must also edit the
@code{Wordchars} node. If a parent language has been specified for the
current language definition it is possible to append to the parent Keywords
by setting the @code{mode} attribute to @code{append}, the default value is
@code{override} meaning that the keywords definition will replace the
parent's one.

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 Wordchars
Most languages have keywords that only contain letters, digits and underscore
characters. However, if you want to also include other special characters
(for instance '<' and '>' in XML), you need to use this tag to let GPS
know. The value of this node is a string made of all the special word
characters. You do not need to include letters, digits or underscores.

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

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

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

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

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

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

This procedure is used by GPS to implement several capabilities such as
listing constructs in the project view, highlighting the current block of
code, going to the next or previous procedure, @dots{}

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

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

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

@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 regular expression defining the beginning of a single line comment
   (ended at the next end of line). This regular expression may contain
   multiple possible line starts, such as @code{;|#} for comments starting
   after a semicolon or after the hash sign. If a parent language has been
   specified for the current language definition it is possible to append
   to the parent New_Line_Comment_Start by setting the @code{mode} attribute to
   @code{append}, the default value is @code{override} meaning that the
   New_Line_Comment_Start definition will replace the parent's one.

   @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 view
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 either one of the following
   predefined categories:
   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,
   or any arbitrary name, which will create a new category.

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

   @item End_Index
   Optional attribute that indicates the index in the pattern used to start
   the next search. Default value is the end of the pattern.

   @item Icon
   Name of a stock icon that should be used for that category (@pxref{Adding stock icons}). This attribute is currently ignored, and is reserved for future
   uses.
   @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 node 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

   e.g:

   @smallexample
      for Compiler_Command ("my_language") use "my_compiler";
   @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 possible 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>&quot;</String_Delimiter>
      <Constant_Character>&apos;</Constant_Character>
      <Can_Indent>True</Can_Indent>
      <Syntax_Highlighting>True</Syntax_Highlighting>
      <Case_Sensitive>False</Case_Sensitive>
    </Context>

    <Categories>
      <Category>
        <Name>package</Name>
        <Pattern>^[ \t]*package[ \t]+((\w|\.)+)</Pattern>
        <Index>1</Index>
      </Category>
      <Category>
        <Name>type</Name>
        <Pattern>^[ \t]*type[ \t]+(\w+)</Pattern>
        <Index>1</Index>
      </Category>
    </Categories>

    <Engine>gpr</Engine>
    <Comment_Line>gpr_comment_line</Comment_Line>
  </Language>
</Custom>
@end smallexample

@c --------------------------------------------------------------------------
@node Defining text aliases
@subsection Defining text aliases
@cindex aliases
@cindex <alias>
@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.

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

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

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

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

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

@item %%
Inserts a percent sign as part of the expanded text

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

@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. You can override this default behavior
by selecting the check button @code{Indent source editor after expansion}.
In this case, GPS will replace the name of the alias by its expansion,
and then automatically recompute the position of each line with its
internal indentation engine, as if the text had been inserted manually.

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
The customization files described earlier can also contain aliases
definition. This can be used for instance to create project or system wide
aliases. All the customization files will be parsed to look for aliases
definition.

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

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

The system files are loaded first, and aliases defined there can be
overridden by the user-defined file.

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

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}.
It has one optional attribute, @code{indent}, which, if set to @i{true},
indicate that GPS should recompute the indentation of the newly inserted
paragraph after the expansion.

@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

Here is an example of an alias file:

@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

@c --------------------------------------------------------------------------
@node Defining project attributes
@subsection Defining project attributes
@cindex project attributes
@cindex <project_attribute>
@c --------------------------------------------------------------------------

@noindent
The project files are required by GPS, and are used to store various
pieces of information related to the current set of source files. This
includes how to find the source files, how the files should be compiled,
or manipulated through various tools, @dots{}.

However, the default set of attributes that are usable in a project file
is limited to the attributes needed by the tool packaged with GPS or GNAT.

If you are delivering your own tools, you might want to store similar
information in the project files themselves, since these are a very
convenient place to associate some specific settings with a given set of
source files.

GPS lets manipulate the contents of projects through XML customization
files and script commands. You can therefore add you own typed attributes
into the projects, so that they are saved automatically when the user
saves the project, and reloaded automatically the next time GPS is started.

@subsubsection Declaring the new attributes

New project attributes can be declared in two ways: either using the advanced
XML tags below, or using the @code{<tool>} tag (@pxref{Defining tool switches}).

The customization files support the @code{<project_attribute>} tag,
which is used to declare all the new attributes that GPS should expect
in a project.  Attributes that have not been declared explictly will
not be accessible through the GPS scripting languagues, and will
generate warnings in the Messages window.

Project attributes are typed: they can either have a single value, or
have a set of such values (a list). The values can in turn be a
free-form string, a file name, a directory name, or a value extracted
from a list of preset values.

Attributes that have been declared in these customization files will
also be graphically editable through the project properties dialog, or
the project wizard. Therefore, you should specify when an attribute is
defined how it should be presented to the GPS user.

The @code{<project_attribute>} tag accepts the following attributes:

@itemize @bullet
@item @code{package} (a string, default value: "")

This is the package in the project file in which the attribute is
stored. Common practice suggests that one such package should be used
for each tool. These packages provide namespaces, so that attributes
with the same name, but for different tools, do not conflict with each
other.

@item @code{name} (a string, mandatory)

This is the name of the attribute. This should be a string with no
space, and that represents a valid Ada identifier (typically, it
should start with a letter and be followed by a set of letters, digits
or underscore characters). This is an internal name that is used when
saving the attribute in a project file.

@item @code{editor_page} (a string, default value: "General")

This is the name of the page in the Project Properties editor dialog
in which the attribute is presented. If no such page already exists, a
new one will be created as needed. If the page already exists, the
attribute will be appended at its bottom.

@item @code{editor_section} (a string, default value: "")

This is the name of the section, inside editor page, in which the
attribute is displayed. These sections are surrounded by frames, the
title of which is given by the @code{editor_section} attribute.
If this attribute is not specified, the attribute is put in an
untitled section.

@item @code{label} (a string, default value: the name of the attribute)

If this attribute is set to a value other than the empty string
@code{""}, a textual label is displayed to the left of the attribute
in the graphical editor. This should be used to identify the
attribute. However, it can be left to the empty string if the
attribute is in a named section of its own, since the title of the
section might be a good enough indication.

@item @code{description} (a string, default value: "")

This is the help message that describes the role of the attribute. It
is displayed in a tooltip if the user leaves the mouse on top of the
attribute for a while.

@item @code{list} (a boolean, default value: "false")

If this is set to @code{"true"}, the project attribute will in fact
contains a list of values, as opposed to a single value. This is used
for instance for the list of source directories in standard projects.

@item @code{ordered} (a boolean, default value: "false")

This is only relevant if the project attribute contains a list of
values. This indicates whether the order of the values is relevant.
In most cases, it will not matter. However, for instance, the order of
source directories matters, since this also indicates where the source
files will be searched, stopping at the first match.

@item @code{omit_if_default} (a boolean, default value: "true")

This indicates whether the project attribute should be set explicitly
in the project if the user has left it to its default value. This can
be used to keep the project files a simple as possible, if all the
tools that will use this project attribute know about the default
value. If this isn't the case, set @code{omit_if_default} to "false"
to force the generation of the project attribute.

@item @code{base_name_only} (a boolean, default value: "false")

If the attribute contains a file name or a directory name, this
indicates whether the full path should be stored, or only the base
name. In most cases, the full path should be used. However, since GPS
automatically looks for source files in the list of directories, for
instance, the list of source files should only contain base
names. This also increases the portability of project files.

@item @code{case_sensitive_index} (a boolean, default value: "false")

This XML attribute is only relevant for project attributes that are
indexed on another one (see below for more information on indexed
attributes). It indicates whether two indexes that differ only by
their casing should be considered the same. For instance, if the index
is the name of one of the languages supported by GPS, the index is
case insensitive since "Ada" is the same as "C". However, if the index
is the name of a file on Windows, the index is case-insensitive.

@item @code{hide_in} (a string, default value: "")

This XML attribute defines the various context in which this attribute
should not be editable graphically. Currently, GPS provides three such
contexts ("wizard", "library_wizard" and "properties", corresponding to the
project creation wizards and the project properties editor). If any of those
context is specified in hide_in, then the widget to edit this
attribute will not be shown. The goal is to keep the graphical
interface simple.

@item @code{disable_if_not_set} (a boolean, default value: "false")

If this attribute is set to "true", the editor for this attribute will be
greyed out if the attribute is not explicitly set in the project. In most cases,
this is not needed, since the default value of the attribute can be used to leave
the editor active at all time. However, when the value of the attribute is
automatically computed depending on other attributes, the default value cannot be
easily specified in the XML file, and in this case it might be easier to grey out
the editor. An extra check box is displayed next to the attribute so that the user
can choose to activate the editor and add the attribute to the project.

@item @code{disable} (a space-separated list of attribute names, default: "")

This is a list of attribute whose editor should be greyed out if the current
attribute is specified. This only works if both the current attribute and the
referenced attributes have their @code{disable_if_not_set} attribute set to "true".
This can be used to have mutually exclusive attributes present in the editor

@end itemize

@subsubsection Declaring the type of the new attributes

The type of the project attribute is specified through one or several
child tags of @code{<project_attribute>}. The following tags are
recognized.

@itemize @bullet
@cindex <string>
@item @code{<string>}

This tag indicates that the attribute is made of one (or more if it is
a list) strings. This
tag accepts the following XML attributes:

@itemize -
@item @code{default} (a string, default value: "")

This gives the default value to be used for the string (and therefore
the project attribute), in case the user hasn't overridden it.

If the attribute's type is a file or a directory, the default value will be
normalized (ie an absolute path will be generated from it, based on the
project's location, where @code{"."} will represent the project's directory).
As a special case, if default is surrounded by parenthesis, no normalization
takes place, so that you can later on test whether the user is still using
the default value or not).

A special case if when @code{default} is set to "project source files". In this
case, this is automatically replaced by the known list of source files for the
project. This doesn't work from the project wizard, since the list of source files
hasn't been computed at that stage.

@item @code{type} (one of "", "file", "directory", default "")

This indicates what the string represents. In the first case, any
value can be used. In the second case, it should represent a file
name, although no check is done to make sure the file actually exists
on the disk. But GPS will be able to do some special marshalling with
the file name. The third case indicates that GPS should expect a
directory.

@item @code{filter} (one of "none", "project", "extending_project")

This attribute is ignored for all types except @code{"file"}. In this case,
it further specifies what kind of files can be used in this attribute. If
the filter is @code{"none"}, then any file anywhere on the system is valid.
If the filter is @code{"project"}, then only files from the selected project
can be specified. If the filter is @code{"extended_project"}, then only the
files from the project extended by the current project can be specified. The
attribute will not be shown if the current project is not an extending project.

@item @code{allow_empty} (one of "True" or "False, default "True")

This attribute indicates whether the value for this attribute can be an
empty string. If not, the user must specify a value or an error message will
be displayed in the project properties editor and project wizard.

@end itemize

@cindex <choice>
@item @code{<choice>}

This tag can be repeated several times. It indicates one of the valid
values for the attribute, and can be used to provide a static list of
such values. If it is combined with a @code{<string>} tag, this
indicates that the attribute can be any string, although a set of
possible values is provided to the user for ease of use.
This tag accepts one optional attribute, @code{"default"}, which is a
boolean. It indicates whether this value is the default to use for the
project attribute.

If several @code{<choice>} tags are used, it is possible that several
of them are part of the default value if the project attribute is a
list, as opposed to a single value.

@cindex <shell>
@item @code{<shell>}

This tag is a GPS scripting command to execute to get a list of valid
values for the attribute. The command should return a list. As for the
@code{<choice>} tag, the @code{<shell>} tag can be combined with a
@code{<string>} tag to indicate that the list of values returned by
the scripting command is only a set of possible values, but that the
project attribute can in fact take any value.

The @code{<shell>} tag accepts two attributes:

@itemize -
@item @code{lang} (a string, default value: "shell")

The scripting language in which the command is written. Currently, the
only other possible value is "python".

@item @code{default} (a string, default value: "")

The default value that the project attribute takes if the user hasn't
overridden it.
@end itemize

@end itemize

@cindex indexed project attributes
@cindex project attributes, indexed
@cindex <index>
@cindex <specialized_index>

In some cases, the type of the project attribute, or at least its
default value, depends on what the attribute applies to. The project
file support this in the form of indexed project attribute. This is
for instance used to specify what should be the name of the executable
generated when compiling each of the main files in the project (ie the
executable name for @code{gps.adb} should be @code{gps.exe}, the one
for @code{main.c} should be @code{myapp.exe}, and so on).

Such attributes can also be declared through XML files. In such cases,
the @code{<project_attribute>} tag should have one @code{<index>}
child, and zero or more @code{<specialized_index>} children.
Each of these two tags in turn take one of the already mentioned
@code{<string>}, @code{<choice>} or @code{<shell>} tag.

The @code{<index>} tag indicates what other project attribute is used
to index the current one. In the example given above for the
executable names, the index is the attribute that contains the list of
main files for the project.

It accepts the following XML attributes:

@itemize @bullet
@item @code{attribute} (a string, mandatory)

The name of the other attribute. This other attribute must be declared
elsewhere in the customization files, and must be a list of values,
not a single value.

@item @code{package} (a string, default value: "")

The package in which the index project attribute is defined. This is
used to uniquely identify homonym attributes.
@end itemize

The @code{<specialized_index>} is used to override the default type of
the attribute for specific values of the index. For instance, the
project files contains an attribute that specify what the name of the
compiler is for each language. It is indexed on the project attribute
that list the languages used for the source files of the project. Its
default value depends on the language ("gnatmake" for Ada, "gcc" for
C, and so on). This attribute accepts requires one XML attribute:

@itemize @bullet
@item @code{value} (a string, mandatory)

This is the value of the attribute for which the type is overriden.
@end itemize

Note that almost all the standard project attributes are defined
through an XML file, @file{projects.xml}, which is part of the GPS
installation. Check this file to get advanced examples on how to
declare project attributes.

@subsubsection Examples

The following example declares three attributes, with a single string
as their value. This string represents a file or a directory in the
last two cases. You can simply copy this into a @file{.xml} file in
your @file{$HOME/.gps/plug-ins} directory, as usual.

@smallexample
<?xml version="1.0"?>
<custom>
  <project_attribute
      name="Single1"
      package="Test"
      editor_page="Tests single"
      editor_section="Single"
      description="Any string">

     <string default="Default value" />
  </project_attribute>

  <project_attribute
      name="File1"
      package="Test"
      editor_page="Tests single"
      editor_section="Single"
      description="Any file" >

      <string type="file" default="/my/file" />
  </project_attribute>

  <project_attribute
      name="Directory1"
      package="Test"
      editor_page="Tests single"
      editor_section="Single"
      description="Any directory" >

      <string type="directory" default="/my/directory/" />
  </project_attribute>
</custom>
@end smallexample

The following example declares an attribute whose value is a
string. However, a list of predefined possible values is also
provided, as an help for interactive edition for the user. If the
@code{<string>} tag wasn't given, the attribute's value would have two
be one of the three possible choices.

@smallexample
<?xml version="1.0" ?>
<custom>
  <project_attribute
      name="Static2"
      package="Test"
      editor_page="Tests single"
      editor_section="Single"
      description="Choice from static list (or any string)" >

      <choice>Choice1</choice>
      <choice default="true" >Choice2</choice>
      <choice>Choice3</choice>
      <string />
  </project_attribute>
</custom>
@end smallexample

The following example declares an attribute whose value is one of the
languages currently supported by GPS. Since this list of languages is
only know when GPS is executed, a script command is used to query this
list.

@smallexample
<?xml version="1.0" ?>
<custom>
 <project_attribute
      name="Dynamic1"
      package="Test"
      editor_page="Tests single"
      editor_section="Single"
      description="Choice from dynamic list" >

      <shell default="C" >supported_languages</shell>
  </project_attribute>
</custom>
@end smallexample

The following example declares an attribute whose value is a set of
file names. The order of files in this list matters to the tools that
are using this project attribute.

@smallexample
<?xml version="1.0" ?>
<custom>
 <project_attribute
      name="File_List1"
      package="Test"
      editor_page="Tests list"
      editor_section="Lists"
      list="true"
      ordered="true"
      description="List of any file" >

      <string type="file" default="Default file" />
  </project_attribute>
</custom>
@end smallexample

The following example declares an attribute whose value is a set of
predefined possible values. By default, two such values are selected,
unless the user overrides this default setting.

@smallexample
<?xml version="1.0" ?>
<custom>
  <project_attribute
      name="Static_List1"
      package="Test"
      editor_page="Tests list"
      editor_section="Lists"
      list="true"
      description="Any set of values from a static list" >

      <choice>Choice1</choice>
      <choice default="true">Choice2</choice>
      <choice default="true">Choice3</choice>
  </project_attribute>
</custom>
@end smallexample

The following example declares an attribute whose value is a
string. However, the value is specific to each language (this could
for instance be used for the name of the compiler to use for a given
language). This is an indexed project attribute. It has two default
values, one for Ada, one for C. All other languages have no default
value.

@smallexample
<?xml version="1.0" ?>
<custom>
  <project_attribute
      name="Compiler_Name"
      package="Test"
      editor_page="Tests indexed"
      editor_section="Single"
      <index attribute="languages" package="">
         <string default="" />
      </index>
      <specialized_index value="Ada" >
         <string default="gnatmake" />
      </specialized_index>
      <specialized_index value="C" >
         <string default="gcc" />
      </specialized_index>
  </project_attribute>
</custom>
@end smallexample

@subsubsection Accessing the project attributes

The new attributes that were defined are accessible from the GPS
scripting languages, like all the standard attributes, @pxref{Querying
project switches}.

You can for instance access the Compiler_Name attribute we created
above with a python command similar to:

@smallexample
GPS.Project.root().get_attribute_as_string ("Compiler_Name", "Test", "Ada")
@end smallexample

You can also access the list of main files for the project, for
instance, by calling

@smallexample
GPS.Project.root().get_attribute_as_list ("main")
@end smallexample

@c --------------------------------------------------------------------------
@node Adding casing exceptions
@subsection Adding casing exceptions
@cindex case_exceptions
@cindex <case_exceptions>
@c --------------------------------------------------------------------------

@noindent
A set of case exceptions can be declared in this file. Each case
exception is put inside the tag @code{<word>} or @code{<substring>}. These
exceptions are used by GPS to set identifiers or keywords case when
editing case insensitive languages (except if corresponding case is
set to Unchanged). @pxref{The Preferences Dialog}.

@smallexample
<?xml version="1.0" ?>
<exceptions>
  <case_exceptions>
     <word>GNAT</word>
     <word>OS_Lib</word>
     <substring>IO</substring>
  </case_exceptions>
</exceptions>
@end smallexample

@c --------------------------------------------------------------------------
@node Adding documentation
@subsection Adding documentation
@cindex <documentation_file>
@c --------------------------------------------------------------------------

@noindent
New documentation can be added in GPS in various ways. This is useful if you
want to point to your own project documentation for instance.

The first possibility is to create a new menu, through a @code{<menu>} tag
in an XML file, associated with an action that either spawn an external
web browser or calls the internal @code{GPS.Help.browse()} shell command.

However, this will not show the documentation in the @code{Help->Contents}
menu, which you also might want to do.

To have both results, you should use the @code{<documentation_file>} tag
in an XML file. These tags are generally found in the @file{gps_index.xml}
files, as documented in @pxref{Adding New Help Files}, but you can in fact
add them in any of your customization files.

The documentation files you display can contain the usual type of html links.
In addition, GPS will treat specially links starting with '%', and consider
them as script commands to execute instead of file to display. The following
example show how to insert a link that will in effect open a file in GPS when
clicked by the user

@smallexample
<a href="%shell:Editor.editor g-os_lib.ads">Open runtime file</a>
@end smallexample

The first word after '%' is the name of the language, and the command to
execute is found after the ':' character.

The @code{<documentation_file>} accepts a number of child nodes:

@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}.
If this child is omitted, you must specify a @code{<shell>} child.

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 shell
This child specifies the name of a shell command to execute to get the
name of the HTML file. This command can for instance create the HTML file
dynamically, or download it locally using some special mechanism.
This child accepts one attribute, @code{"lang"}, which is the name of the
language in which the command is written

@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

The @code{<menu>} child tag accepts two attributes.

@table @b
@item before (optional, default="")

The name of the menu before which the new entry should be inserted. If the
new menu is inserted in some submenus, this tag controls the deeper nesting.
Parent menus are created as needed, but if you wish to control their specific
order, you should create them first with a @code{<menu>} tag.

@item after (optional, default="")

The name of the menu after which the new entry should be inserted.
@end table

@end table

The following example shows how to create a new entry "item" in the Help
menu, that will display @file{file.html}. The latter is searched in the
@code{GPS_DOC_PATH} list of directories.

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

@cindex <doc_path>
As mentioned above, HTML files are looked for through the @code{GPS_DOC_PATH}
environment variable. However, you can also use the @code{<doc_path>} XML
node to defined additional directories to be searched.

Such a directory is relative to the installation directory of GPS.

@smallexample
<?xml version="1.0"?>
<GPS>
   <doc_path>doc/application/</doc_path>
</GPS>
@end smallexample

will add the directory @file{<prefix>/doc/application} to the search path
for the documentation.

Such a directory can also be added through Python, as in:

@smallexample
GPS.HTML.add_doc_directory ('doc/application')
@end smallexample

@c --------------------------------------------------------------------------
@node Adding stock icons
@subsection Adding stock icons
@cindex stock_icons
@cindex <stock_icons>
@c --------------------------------------------------------------------------

@noindent
XML files can be used to define ``stock icons''. Stock icons are pictures
that are identified by their label, and which are used through GPS in various
places, such as buttons, menus, toolbars, and so on.

The stock icons must be declared using the tag @code{<icon>}, within the global
tag @code{<stock>}. The attribute @code{id} indicates the label used to identify
the stock icon, and the attribute @code{file} points to the file which contains
the actual picture, either in absolute format, or relative to the directory
which contains the XML file.

If the stock icon is to be used in a toolbar, use the attribute @code{label} to
specify the text to display in the toolbar, under the button, when the toolbar
is configured to show text.

For icons that are intended to be displayed at multiple sizes, you can specify
multiple files corresponding to these multiple sizes. This is done by adding
children to the main icon node, with the tag @code{alternate}, containing
a @code{file} attribute and a @code{size} attribute which correspond to the
size for which this alternate source should be used.

Possible sizes are:

@table @code
@item 1
Menu item (ideal size: 16x16 pixels)

@item 2
Button in a small toolbar (ideal size: 18x18 pixels)

@item 3
Button in a large toolbar (ideal size: 24x24 pixels)

@item 4
Image for a standard button (ideal size: 20x20 pixels)

@item 5
Image used during drag-and-drop operation (ideal size: 32x32 pixels)

@item 6
Main image in a dialog (ideal size: 48x48 pixels)

@end table

Here is an example:
@smallexample
<?xml version="1.0"?>
<my_visual_preferences>
  <stock>
    <icon id="myproject-my-picture" file="icons/my-picture.png" />

    <icon id="myproject-multipurpose-image"
           label="do something"
           file="icons/icon_default.png">
       <alternate file"icons/icon_16.png" size="menu" />
       <alternate file"icons/icon_24.png" size="large_toolbar" />
       <alternate file"icons/icon_20.png" size="button" />
    </icon>

  </stock>
</my_visual_preferences>
@end smallexample

Note: as shown in the example above, it is a good practice to prefix the label
by a unique name (e.g. @code{myproject-}), in order to make sure that
predefined stock icons will not get overridden by your icons.

@c ??? Not available with docgen2, this needs to be implemented.
@c --------------------------------------------------------------------------
@c @node Defining a documentation format
@c @subsection Defining a Documentation format
@c @cindex documentation
@c @cindex HTML
@c @cindex templates files
@c --------------------------------------------------------------------------

@c GPS has support for textual (as opposed to binary format like PDF)
@c documentation format. A textual documentation format can be described
@c using external template files. This way, it is possible to add support
@c for new textual documentation format by providing a set of templates files.
@c
@c The node name to define a new documentation format is @code{docgen_backend}.
@c
@c The attributes for this node are:
@c
@c @table @code
@c @item name (string)
@c The name of the documentation format (for example HTML).
@c
@c @item format (string)
@c The format is either @b{text} or @b{binary}. Only @b{text} is
@c supported at the moment.
@c @end table
@c
@c There are two categories of children. One is to describe the format
@c itself, the other is to specify the set of template to use. In the
@c latter case the children's name are ending with @code{_template}:
@c
@c @table @code
@c @item extension
@c The extension to use for the generated files. This name is also used
@c as part of the directory name under which the documentation is generated.
@c
@c @item description
@c A description about the documentation format. GPS uses this description
@c in the documentation selection dialog.
@c
@c @item file_header_template
@c Point to a template file used as header for each generated files.
@c
@c @item file_footer_template
@c Point to a template file used as footer for each generated files.
@c
@c @item comment_template
@c Point to a template file used to output comment strings.
@c
@c @item keyword_template
@c Point to a template file used to output keywords.
@c
@c @item string_template
@c Point to a template file used to output strings.
@c
@c @item char_template
@c Point to a template file used to output characters.
@c
@c @item subtitle_template
@c Point to a template file used to output a subtitle give its name, size and
@c indentation level.
@c
@c @item package_desc_template
@c Point to a template file used to output package's description.
@c
@c @item package_template
@c Point to a template file used to output the package declaration or
@c ending.
@c
@c @item with_template
@c Point to a template file used to output with clauses.
@c
@c @item variable_template
@c Point to a template file used to output variables declarations.
@c
@c @item exception_template
@c Point to a template file used to output exception declaration.
@c
@c @item type_template
@c Point to a template file used to output type declarations.
@c
@c @item tagged_type_template
@c Point to a template file used to output tagged types.
@c
@c @item calls_references_template
@c Point to a template file used to output subprograms calls.
@c
@c @item caller_references_template
@c Point to a template file used to output caller references.
@c
@c @item entity_template
@c Point to a template file used to output entity.
@c
@c @item subprogram_template
@c Point to a template file used to output subprograms.
@c
@c @item header_template
@c Point to a template file used to output the start a package description.
@c
@c @item footer_template
@c Point to a template file used to output the end of a package description.
@c
@c @item private_header_template
@c Point to a template file used to output the start of package's private section.
@c
@c @item main_frame_template
@c Point to a template file used to output the main file (the file
@c @file{index.html} in the HTML backend for example).
@c
@c @item unit_index_header_template
@c Point to a template file used to output the units index header.
@c
@c @item subprogram_index_header_template
@c Point to a template file used to output the subprograms index header.
@c
@c @item type_index_header_template
@c Point to a template file used to output the types index header.
@c
@c @item tagged_type_index_header_template
@c Point to a template file used to output the tagged types index header.
@c
@c @item item_index_template
@c Point to a template file used to output an item index.
@c
@c @item tagged_type_index_template
@c Point to a template file used to output the tagged types index.
@c
@c @item private_index_header_template
@c Point to a template file used to output the private types index header.
@c
@c @item public_index_header_template
@c Point to a template file used to output the public types index header.
@c
@c @item index_footer_template
@c Point to a template file used to output the end of indexes.
@c
@c @item block_template
@c Point to a template file used to output block of text with a reference.
@c
@c @item link_template
@c Point to a template file used to output all cross references.
@c
@c @item description_template
@c Point to a template file used to output subprograms description based
@c on comments found just below its spec.
@c @end table
@c
@c All template files are given as relative path. GPS will first look for the
@c template file under @code{share/gps/docgen} and if not found it looks
@c under @code{$HOME/.gps/docgen}.
@c
@c A template file is a file that contains tags and commands. Those files
@c are parsed by the @code{Templates Parser} module as found in
@c @code{AWS}. We give hereafter a short description of this format, for
@c a complete description see the Templates Parser User's Guide.
@c
@c @table @code
@c @item simple tag
@c A simple tag is surrounded by @code{@@_} and @code{_@@} like in
@c @code{@@_NAME_@@}. The templates engine will replace @code{@@_NAME_@@}
@c with the value associated with the tag named @code{NAME}.
@c
@c @item vector tag
@c A vector tag contains a set of values. Each value will be used in
@c sequence if the tag appears inside a @code{TABLE} command tag.
@c
@c For example, if the vector tag COLOR contains the three values Red,
@c Green and Blue then:
@c
@c @smallexample
@c @@@@TABLE@@@@
@c    > @@_COLOR_@@
@c @@@@END_TABLE@@@@
@c @end smallexample
@c
@c Will be expanded as:
@c
@c @smallexample
@c    > Red
@c    > Green
@c    > Blue
@c @end smallexample
@c
@c @item filter
@c
@c Filters can be added to any tag. For example it is possible to output
@c all values in upper case by applying the @code{UPPER} filter in the previous
@c example.
@c
@c @smallexample
@c @@@@TABLE@@@@
@c    > @@_UPPER:COLOR_@@
@c @@@@END_TABLE@@@@
@c @end smallexample
@c
@c Will be expanded as:
@c
@c @smallexample
@c    > RED
@c    > GREEN
@c    > BLUE
@c @end smallexample
@c
@c It exists many filters, see the Template Parser User's Guide for a
@c complete description.
@c @end table
@c
@c Note that each HTML template files, provided with GPS, contains a
@c complete description of the usage of each tag in the header comments.
@c
@c --------------------------------------------------------------------------
@node Remote programming customization
@subsection Remote programming customization
@cindex remote
@c --------------------------------------------------------------------------

@menu
* Defining a remote connection tool::
* Defining a shell::
* Configuring rsync usage::
* Defining a remote server::
* Defining a remote path translation::
@end menu

@noindent

The configuration of the remote programming functionality has two
separate parts: the tools configuration (remote connection tools,
shells, and rsync parameters) and the servers configuration.

The first part (see @ref{Defining a remote connection tool},
@ref{Defining a shell} and @ref{Configuring rsync usage}) is handled
by a pre-installed file in the plug-ins directory called
@file{protocols.xml}.

The second part (see @ref{Defining a remote server} and @ref{Defining
a remote path translation}), when configured via the user interface
(see @ref{Setup the remote servers}), will create a remote.xml file in
the user's gps directory. System-wide servers can be also installed.

@c --------------------------------------------------------------------
@node Defining a remote connection tool
@subsubsection Defining a remote connection tool
@cindex remote
@c --------------------------------------------------------------------

@noindent
Several remote access tools are already defined in GPS: ssh, rsh,
telnet and plink. It is possible to add other tools, using the node
@code{remote_connection_config}.

The attributes for this node are:

@table @code
@item name (string) (mandatory)
The name of the tool. This name does not necessarilly correspond to
the command used to launch the tool.

@end table

The following children are defined:

@table @code
@item start_command (mandatory)
The command used to launch the tool.
This tag supports the @code{use_pipes} attribute. This attribute selects on
Windows the way GPS will launch the remote tools, and can take the following
values:
@table @code
@item true
use pipes to launch the tool.
@item false (default)
use a tty emulation, which is a bit slower but allow
 password prompts retrieval with some tools.
@end table
Note that this argument has effects only on Windows platforms.

@item start_command_common_args (optional)
The arguments that are provided to the tool. This string can contain the
following replacement macros:
@table @code
@item %C
is replaced by the command executed on the remote host (e.g. the shell command)
@item %h
is replaced by the remote host name
@item %U
is replaced by the start_command_user_args, if a user is specified
@item %u
is replaced by the user name
@end table

Note that if neither %u nor %U is found, and a user is specified in the remote
connection configuration, then the start_command_user_args is placed at the
beginning of the arguments.

@item start_command_user_args (optional)
The arguments used to define a specific user during connection. %u is replaced
 by the user name

@item send_interrupt (optional)
The characters sequence to send to the remote tool to interrupt the remote
 application. If unset, then an Interrupt signal is sent directly to the remote
 tool.

@item user_prompt_ptrn (optional)
A regular expression, used to catch user name prompts from the
connection tool. If undefined, a default regular expression is used.

@item password_prompt_ptrn (optional)
@cindex password
A regular expression, used to catch password prompts from the
connection tool. If undefined, a default regular expression is used.

@item passphrase_prompt_ptrn (optional)
A regular expression, used to catch passphrase prompts from the
connection tool. If undefined, a default regular expression is used.

@item extra_ptrn (optional)
Complex child. Used to catch extra prompts from the connection tool,
other than password, passphrase or usename prompts. This tag has an
attribute @code{auto_answer} telling if GPS automatically answers to
this prompt, or ask the user. If auto_answer is @code{true}, then this
tag needs an @code{answer} child, whose value is used for the answer. If
auto_answer is @code{false}, then this tag needs a @code{question} child,
whose value is used as question to the end user.

@c ??? need an example

@end table

@c --------------------------------------------------------------------
@node Defining a shell
@subsubsection Defining a shell
@cindex remote
@c --------------------------------------------------------------------

@noindent
Several shells are already defined in GPS: sh, bash, csh, tcsh and
cmd.exe (Windows). It is possible to add other shells, using the node
@code{remote_shell_config}.

The attributes for this node are:

@table @code
@item name (string) (mandatory)
The name of the shell. This name does not necessarilly correspond to
the command used to launch the shell.

@end table

The following children are defined:

@table @code
@item start_command (mandatory)
The command used to launch the shell. If arguments are required, they
should be put here, separated with spaces.

@item generic_prompt (optional)
The regular expression used to identify a prompt after the initial
connection. If not set, a default value is used.

@item gps_prompt (mandatory)
The regular expression used to identify a prompt after the initial
setup is performed. If not set, a default value is used.

@item filesystem (mandatory)
Takes the following values: @code{unix} or @code{windows}. This is the
filesystem used by the shell.

@item init_commands (optional)
Complex child. Each @code{cmd} child contains a command used to
initialise a new session.

@item exit_commands (optional)
Complex child. Each @code{cmd} child contains a command used to
exit a session.

@item no_echo_command (optional)
Command used to suppress the echo of the remote shell.

@item cd_command (mandatory)
Command used to go to a directory. @code{%d} is replaced by the
directory's full name.

@item get_status_command (mandatory)
Command used to retrieve the status of the last command launched.

@item get_status_ptrn (mandatory)
Regular expression used to retrieve the status returned by
@code{get_status_command}. A pair of parenthesis is required, and
identifies the status.

@end table

@c --------------------------------------------------------------------
@node Configuring rsync usage
@subsubsection Configuring rsync usage
@cindex rsync
@c --------------------------------------------------------------------

@noindent
GPS has native support for the rsync tool, for paths synchronization
during remote programming operations.

By default, GPS will use --rsh=ssh option if ssh is the main
connection tool for the concerned server. It will also define the -L
switch when transfering files to a Windows local host.

It is possible to define additional arguments to rsync using the
@code{rsync_configuration} tag.

This tag accepts the child tagged @code{arguments}, and containing
additional arguments to pass to rsync.

@c --------------------------------------------------------------------
@node Defining a remote server
@subsubsection Defining a remote server
@cindex server
@cindex remote
@c --------------------------------------------------------------------

@noindent
Remote servers can be defined via the user interface, as described in
@ref{Setup the remote servers}. This user interface will create a
remote.xml file in the user's gps directory, which in turn can be
installed in any plug-ins directory to set the values
system-wide. This file will define for each server the node
@code{remote_machine_descriptor}.

The attributes for this node are:
@table @code
@item nickname (mandatory)
Identifies uniquely the server in GPS.

@item network_name (mandatory)
The server's network name or IP address.

@item remote_access (mandatory)
The tool's name used to access the server. Shall point to one of the
tools defined in @ref{Defining a remote connection tool}.

@item remote_shell (mandatory)
The shell's name used to access the server. Shall point to one of the
shells defined in @ref{Defining a shell}.

@item remote_sync (mandatory)
The remote file synchronisation tool used to synchronize files between
the local host and the server. Only @code{rsync} is recognized currently.

@item debug_console (optional)
Can take the value @code{True} or @code{False}. Tells if a debug console
should be displayed during connection with a remote host. False by default.
@end table

The children for this node are:
@table @code
@item extra_init_commands (optional)
Complex child. Can contain @code{cmd} children whose values are used
to set server specific initialization commands.

@item max_nb_connections (optional)
Positive number representing the maximum number of simultaneous
connections GPS can launch.

@item timeout (optional)
Positive number representing a timeout value (in ms) used for every
action performed on the remote host.
@end table

@c --------------------------------------------------------------------
@node Defining a remote path translation
@subsubsection Defining a remote path translation
@cindex server
@cindex path
@cindex remote
@c --------------------------------------------------------------------

@noindent
Remote path translation can also be defined via the user interface, as
described in @ref{Setup the remote servers}. The remote paths
translation are defined with the node @code{remote_path_config}.

The attributes for this node are:
@table @code
@item server_name (mandatory)
The server name concerned by the paths translation.
@end table

The @code{remote_path_config} node contains @code{mirror_path}
children.

The attributes for the node @code{mirror_path} are:
@table @code
@item local_path (mandatory)
The absolute local path, expressed using the local filesystem
standards.
@item remote_path (mandatory)
The absolute remote path, expressed using the remote filesystem
standards.
@item sync (mandatory)
Specify the synchronization mechanism used for the paths
(see @ref{Paths settings}). Possible values are
@code{NEVER}, @code{ONCE_TO_LOCAL}, @code{ONCE_TO_REMOTE} and @code{ALWAYS}.
@end table

@c --------------------------------------------------------------------------
@node Customizing build Targets and Models
@subsection Customizing build Targets and Models
@c --------------------------------------------------------------------------

@noindent
The information displayed in @ref{The Target Configuration Dialog} and in
the Mode selection can be customized through XML.

@menu
* Defining new Target Models::
* Defining new Targets::
* Defining new Modes::
@end menu

@node Defining new Target Models
@subsubsection Defining new Target Models
@cindex Model

Models are defined in a @code{target-model} node which has one attributes,
@code{name}, which contains the name of the model, and which supports the
following sub-nodes:

@table @code
@item <icon>
   The stock name of the icon to associate by default with targets of this
   model.
@item <description>
   A one-line description of what the Model supports
@item <server>
   Optional, defaulting to @code{Build_Server}. Indicates the server used for
   launching Targets of this model. @xref{Remote operations}.
@item <is-run>
   Optional, defaulting to @code{False}. A boolean indicating whether this
   target corresponds to the launching of an executable rather than a build.
   Targets with such a model are launched through an interactive console in
   GPS, and their output is not parsed for errors.
@item <uses-shell>
   Optional, defaulting to @code{False}. A boolean indicating whether Targets
   of this model should be launched via the shell pointed to by the SHELL
   environment variable.
@item <command-line>
   Contains a number of @code{<arg>} nodes, each containing an argument of the
   default command line for this model, starting with the executable.
@item <switches command="executable_name">
   The graphical description of the switches.
   (@pxref{Defining tool switches})
@end table

@smallexample
<?xml version="1.0" ?>
   <my_model>
   <target-model name="gprclean" category="">
      <description>Clean compilation artefacts with gprclean</description>
      <command-line>
         <arg>gprclean</arg>
         <arg>-P%PP</arg>
         <arg>%X</arg>
      </command-line>
      <icon>gps-clean</icon>
      <switches command="%(tool_name)s" columns="1">
         <check label="Clean recursively" switch="-r"
                tip="Clean all projects recursively" />
      </switches>
   </target-model>
</my_model>
@end smallexample

@node Defining new Targets
@subsubsection Defining new Targets
@cindex Target

Targets are defined in a @code{target} node which has three attributes:

@table @code
@item name
   Contains the name of the Target. It must be a unique name.
   Underscores are interpreted as menu mnemonics. To represent an actual
   underscore, use a double underscore.
@item category
   The category which contains the Target, for purposes of ordering the
   tree in the Target Configuration Dialog, and for ordering in the Build
   menu.Underscores are interpreted as menu mnemonics. To represent an actual
   underscore, use a double underscore.
   If @code{category} begins and ends with an underscore, the menu for the
   Target is placed in the toplevel Build menu.
@item model
   The name of the Model of which this Target inherits initially.
@end table

@table @code
@item <icon>
   The stock name of the icon to associate by default with the Target.
@item <in-toolbar>
   Optional, defaulting to @code{False}. A boolean indicating whether the
   Target should have an associated icon in the Toolbar.
@item <in-menu>
   Optional, defaulting to @code{True}. A boolean indicating whether the
   Target should have an associated entry in the Build menu.
@item <in-contextual-menus-for-projects>
   Optional, defaulting to @code{False}. A boolean indicating whether the
   Target should have an associated entry in the contextual menu for projects.
@item <in-contextual-menus-for-files>
   Optional, defaulting to @code{False}. A boolean indicating whether the
   Target should have an associated entry in the contextual menu for files.
@item <read-only>
   Optional, defaulting to @code{False}. A boolean indicating whether the
   Target can be removed by the user.
@item <target-type>
   Optional, defaulting to an empty string. A string indicating whether the
   Target represents a simple target (if empty), or a
   family of Targets. The name represents a parameter passed to the
   @code{compute_build_targets} hook. If set to @code{main}, a new subtarget
   will be create for each Main source defined in the project.
@item <launch-mode>
   Optional, defaulting to @code{MANUALLY}. Indicates how the Target should be
   launched. Possible values are @code{MANUALLY}, @code{MANUALLY_WITH_DIALOG},
   @code{MANUALLY_WITH_NO_DIALOG}, and @code{ON_FILE_SAVE}.
@item <server>
   Optional, defaulting to @code{Build_Server}. Indicates the server used for
   launching Target. @xref{Remote operations}.
@item <command-line>
   Contains a number of @code{<arg>} nodes, each containing an argument of the
   default command line for this Target, starting with the executable.
@end table

@smallexample
<?xml version="1.0" ?>
<my_target>
   <target model="gprclean" category="C_lean" name="Clean _All">
       <in-toolbar>TRUE</in-toolbar>
       <icon>gps-clean</icon>
       <launch-mode>MANUALLY_WITH_DIALOG</launch-mode>
       <read-only>TRUE</read-only>
       <command-line>
          <arg>%gprclean</arg>
          <arg>-r</arg>
          <arg>%eL</arg>
          <arg>-P%PP</arg>
          <arg>%X</arg>
       </command-line>
  </target>
</my_target>
@end smallexample

@node Defining new Modes
@subsubsection Defining new Modes
@cindex Mode

Modes are defined in a @code{builder-mode} node which has one attributes,
@code{name}, which contains the name of the model, and which supports the
following sub-nodes:

@table @code
@item <description>
   A one-line description of what the Mode does
@item <subdir>
   Optional. The base name of the subdirectory to create for this Mode.
   The macro argument @code{%subdir} in the @code{extra-args} nodes will be
   substituted with this.
@item <supported-model>
   The name of a model supported by this Mode. There can be multiple
   @code{supported-model} nodes, each corresponding to a supported Model.
   Optionally, you can specify a @code{filter} attribute for this node,
   corresponding to the switches that are relevant for this mode. By default,
   all switches will be taken into account.
   The @code{extra-args} of the Mode that match @code{filter} will be passed
   to commands of the supported Models.
@item <extra-args>
   Contains a list of @code{<arg>} nodes, each containing one extra argument
   to append to the command line when launching Targets while this Mode is
   active.
   Macros are supported in the @code{<arg>} nodes.
@end table

@smallexample
<?xml version="1.0" ?>
<my_mode>
 <builder-mode name="optimization">
  <description>Build with code optimization activated</description>
  <subdir>optimized_objects</subdir>
  <supported-model>builder</supported-model>
  <supported-model>gnatmake</supported-model>
  <supported-model filter="--subdirs=">gprclean</supported-model>
  <extra-args>
     <arg>--subdirs=%subdir</arg>
     <arg>-cargs</arg>
     <arg>-O2</arg>
  </extra-args>
 </builder-mode>
</my_mode>
@end smallexample

@c --------------------------------------------------------------------------
@node Toolchains customization
@subsection Toolchains customization
@c --------------------------------------------------------------------------

@noindent
The list of toolchains and their values presented in the project editor
(@pxref{The Project Wizard}) can be customized through XML. The GPS default
list is contained in @code{toolchains.xml}. You can add your own toolchain
by providing an xml description following the below described structure:

@table @code
@item <toolchain_default>
  Contains the default names for the different tools used by all toolchains.
  The final name used will be @code{toolchain_name-default_name}.
@item <toolchain name="name">
  Defines a toolchain using name "name". This toolchain can override the
  default values defined in the toolchain_default above.
@end table

Each of the above tags can have the following chilren

@table @code
@item <gnat_driver>
  Defines the gnat driver to use.
@item <gnat_list>
  Defines the gnat list tool to use.
@item <debugger>
  Defines the debugger to use.
@item <cpp_filt>
  Not used by GPS.
@item <compiler lang="lang">
  Defines the compiler to use to compile language "lang"
@end table

The toolchain_default values can either be overriden or nullified by just
providing the same tab with an empty value in a toolchain definition.

@c --------------------------------------------------------------------------
@node Adding support for new tools
@section Adding support for new tools
@cindex external tool
@cindex <tool>
@c --------------------------------------------------------------------------

@menu
* Defining supported languages::
* Defining default command line::
* Defining tool switches::
* Executing external tools::
@end menu

@noindent
GPS has built-in support for external tools. This feature can be used to
support a wide variety of tools (in particular, to specify different
compilers). Regular enhancements are done in this area, so if you are
planning to use the external tool support in GPS, check for the latest GPS
version available.

Typically, the following things need to be achieved to successfully use a
tool:

@itemize @bullet
@item Specify its command line switches
@item Pass it the appropriate arguments depending on the current context, or
      on user input
@item Spawn the tool
@item Optionally parse its result and act accordingly
@end itemize

Each of these points is discussed in further sections. In all these cases, most
of the work can be done statically through XML customization files.
These files have the same format as other XML customization files
(@pxref{Customizing through XML and Python files}), and the tool descriptions are found in
@code{<tool>} tags.

This tag accepts the following attributes:

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

@item package (Default value is ide)
This optional attribute specifies which package should be used in the project
to store information about this tool, in particular its switches. Most of
the time the default value should be used, unless you are working with one of
the predefined packages.

See also @xref{Defining project attributes}, for more information on defining
your own project attributes. Using the "package", "attribute" or "index"
XML attributes of <tool> will implicitly create new project attributes as
needed.

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

@item attribute (Default value is default_switches)
This optional attribute specifies the name of the attribute in the project
which is used to store the switches for that tool.

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

@item override (Default value is 'false')
This optional attribute specifies whether the tool definition can be redefined.
The accepted values are 'true' or 'false'. If override is not set, and the tool
is defined several times, then a Warning will be displayed.

@end table

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

@table @code
@item <switches>
   (@pxref{Defining tool switches})
@item <language>
   (@pxref{Defining supported languages})
@item <initial-cmd-line>
   (@pxref{Defining default command line})
@end table

@c --------------------------------------------------------------------------
@node Defining supported languages
@subsection Defining supported languages
@cindex <language>
@c --------------------------------------------------------------------------

@noindent
This is the language to which the tool applies.  There can be from no to any
number of such nodes for one @code{<tool>} tag.

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

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

@smallexample
<?xml version="1.0" ?>
<my_tool>
  <tool name="My Tool" >
    <language>Ada</language>
    <language>C</language>
  </tool>
</my_tool>
@end smallexample

@c --------------------------------------------------------------------------
@node Defining default command line
@subsection Defining default command line
@cindex <initial-cmd-line>
@c --------------------------------------------------------------------------

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

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

@smallexample
<?xml version="1.0" ?>
<my_tool>
  <tool name="My tool" >
     <initial-cmd-line>-a -b -c</initial-cmd-line>
  </tool>
</my_tool>
@end smallexample

@c --------------------------------------------------------------------------
@node Defining tool switches
@subsection Defining tool switches
@cindex <switches>
@c --------------------------------------------------------------------------

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

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

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

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

This @code{<switches>} tag accepts the following attributes:

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

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

@item separator (default value is "")
This attribute specifies the default character that should go between a switch
and its value, to distinguishes cases like "-a 1", "-a1" and "-a=1". This can
be overridden separately for each switch. Note that if you want the separator
to be a space, you must use the value @code{"&#32;"} rather than @code{" "},
since XML parser must normalize the latter to the empty string when reading
the XML file.

@item use_scrolled_window (Default value is false)
This optional attribute specifies if the boxes of the project editor are placed
into scrolled window. This is particularily useful if the number of displayed
switches if important.

@item show_command_line (Default value is true)
If this attribute is set to "false", the command line will not be displayed
in the project properties editor. This can be used for instance if you only
want users to edit it through the buttons and other widgets, and not directly.

@item switch_char (Default value is "-")
This is the leading character of command line arguments that indicate they
are considered as switches. Arguments not starting with this character will
be kept as is, and cannot have graphical widgets associated with them

@item sections (Default value is empty)
This is a space separated list of switches delimiting a section (such as
"-bargs -cargs -largs"). A section of switches is a set of switches that
need to be grouped together and preceded by a specific switch. Sections are
always placed at the end of the command line, after regular switches.

@end table

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

@table @code
@item line (default value is 1)
This indicates the row of the frame that should contain the switch. See the
description of @code{lines} above.

@item column (default value is 1)
This indicates the column of the frame that should contain the switch. See the
description of @code{columns} above.

@item label (mandatory)
This is the label which is displayed in the graphical interface

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

@item switch-off (default value is empty)
This attribute is used for @code{<check>} tags, and indicates the switch
used for deactivating the concerned feature. This is useful for features that
are on by default on certain occasions, but can be individually deactivated.

@item section (default value is empty)
This is the switch section delimiter (such as "-cargs"). See the 'sections'
attribute of the tag 'switches' for more information.

@item tip (default value is empty)
This is the tooltip which describes that switch more extensively. It is
displayed in a small popup window if the user leaves the mouse on top of
the widget. Note that tags accepting the tip attribute also accept a single
child @code{<tip>} whose value will contain the text to be displayed. The
advantage of the latter is that the text formatting is then kept.

@item before (default value is "false")
This attribute is used to indicate that a switch needs to be always inserted
at the begining of the command line.

@item min (default value is 1)
This attribute is used for @code{<spin>} tags, and indicates the minimum
value authorized for that switch.

@item max (default value is 1)
This attribute is used for @code{<spin>} tags, and indicates the maximum
value authorized for that switch.

@item default (default value is 1)
This attribute is used for @code{<check>} and @code{<spin>} tags. See the
description below.

@item noswitch (default is empty)
This attribute is only valid for @code{<combo>} tags, and described below.

@item nodigit (default is empty)
This attribute is only valid for @code{<combo>} tags, and described below.

@item value (mandatory)
This attribute is only valid for @code{<combo-entry>} tags.

@item separator (default is the value given to @code{<switches>}
This attribute specifies the separator to use between the switch and its value.
See the description of this attribute for @code{<switches>}.

@end table

Here are the valid children for @code{<switches>}:

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

Extra attributes for @code{<title>} are:

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

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

@item <check>
@cindex <check>
This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},
@code{switch-off}, @code{section}, @code{default}, @code{before} and @code{tip}
attributes.

This tag doesn't have any value. An optional @code{<tip>} child can be present.

It creates a toggle button. When the latter is active, the text defined in the
switch attribute is added as is to the command line. The switch can be also
activated by default (@code{default} attribute is "on" or "true"). In this
case, deactivating the switch will add @code{switch-off} to the command line.

@item <spin>
@cindex <spin>
This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},
@code{section}, @code{tip}, @code{min}, @code{max}, @code{separator} and
@code{default} attributes.

This tag doesn't have any value. An optional @code{<tip>} child can be present.

This switch will add the contents of the @code{switch} attribute followed by
the current numeric value of the widget to the command line. This is typically
used to indicate indentation length for instance.
If the current value of the widget is equal to the @code{default} attribute,
then nothing is added to the command line.

@item <radio>
@cindex <radio>
@cindex <radio-entry>
This tag accepts the @code{line} and @code{column} attributes. It groups any
number of children, each of which is associated with its own switch. However,
only one of the children can be selected at any given time.

The children must have the tag @code{radio-entry}. This tag accepts the
attributes @code{label}, @code{switch}, @code{section}, @code{before} and
@code{tip}. As a special case, the switch attribute can have an empty value
("") to indicate this is the default switch to use in this group of radio
buttons.

This tag doesn't have any value. An optional @code{<tip>} child can also be
present.

@item <field>
@cindex <field>
This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},
@code{section}, @code{separator}, @code{before} and @code{tip} attributes.

This tag doesn't have any value. An optional @code{<tip>} child can be present.

This tag describes a text edition field, which can
contain any text the user types. This text will be prefixed by the value of
the @code{switch} attribute, and the separator (by default nothing). If no text
is entered in the field
by the user, nothing is put on the command line.

This tag accepts two extra attributes:

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

   @item as-file (optional)
   @cindex as-file
   This attribute is similar to @code{as-directory}, but opens a dialog to
   select a file instead of a directory. If both attributes are set to "true",
   the user will select a file.
   @end table

@item <combo>
@cindex <combo>
@cindex <combo-entry>
This tag accepts the @code{line}, @code{column}, @code{label}, @code{switch},
@code{section}, @code{before}, @code{tip}, @code{noswitch}, @code{separator}
and @code{nodigit} attributes.

The tag @code{<combo>} accepts any number of @code{combo-entry} children tags,
each of which accepts the @code{label} and @code{value} attribute. An optional
@code{<tip>} child can also be present.

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

If the value of the current entry is that of the @code{noswitch} attribute,
then nothing is put in the command line.

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

This tag accepts any number of children, which are the same as the
@code{<switches>} attribute itself.

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

It has its own set of attributes:

   @table @code
   @item master-page master-switch master-section
   These two attributes define the switch that possibly forces a specific
   setting on the slave switch. In our example, they would have the values
   "Make" and "-g".
   The switch referenced by these attributes must be of type @code{<check>}
   or @code{<field>}. If it is part of a section, then 'master-section' needs
   to be defined. If the check button is selected, it forces the
   selection of the slave check button. Likewise, if the field is set to
   any value, it forces the selection of the slave.

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

   @item master-status slave-status
   These two switches indicate which state of the master switch forces which
   state of the slave-status. In our example, they would have the values
   "on" and "on", so that when the make debug information is activated, the
   compiler debug information is also activated. However, if the make debug
   information is not activated, no specific setup is forced for the compiler
   debug information.
   if master-status is "off" and the master switch is a field, then the
   status of the slave will be changed when no value is set in the field.
   @end table

@item <default-value-dependency>
@cindex <default-value-dependency>
This tag is used to describe a relationship between two switches. It is
slightly different from the <dependency> tag in that the relationship concerns
only the default activation states. It is used for instance when the "-gnatwa"
switch is selected for the "Ada" Compiler, which imply that the default values
for "-gnatwc", "-gnatwd", etc. become activated by default. They can however
still be deactivated with respectively "-gnatwC" and "-gnatwD".

It has its own set of attributes:
   @table @code
   @item master-switch
   This is the switch that triggers the dependency. If @code{master-switch} is
   present in the command line, then the switch's default status of
   @code{slave-switch} is modified accordingly.

   @item slave-switch
   This is the switch whose default value depends on @code{master-switch}. This
   needs to be a switch already defined in a @code{<switch>} tag. It can match
   its 'switch' or 'switch-off' attributes. In the latter case, the
   slave-switch default value is deactivated if master-switch is present.
   @end table

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

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

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

There are two possible uses for this tag:
@itemize -
@item If the "alias" attribute is not specified, then the "switch" attribute
indicates that all switches starting with that prefix should be grouped.
For instance, if you pass "-gnatw" as the value for the "switch" attribute,
then a command line with "-gnatwa -gnatw.b" will in fact result in "-gnatwa.b".

@item If the "alias" attribute is specified, then the "switch" attribute is
considered as a shorter way of writting "alias". For instance, if "switch"
is "-gnatyy" and "alias" is "-gnaty3abcefhiklmnprst", then the user can simply
type "-gnatyy" to mean the whole set of options.
@end itemize

The same "switch" attribute can be used in two expansion nodes if you want
to combine the behavior.

For historical reasons, this tag accepts @code{<entry>} children, but these
are no longer used.

@end table

@c --------------------------------------------------------------------------
@node Executing external tools
@subsection Executing external tools
@c --------------------------------------------------------------------------

@menu
* Chaining commands::
* Saving open windows::
* Querying project switches::
* Querying switches interactively::
* Redirecting the command output::
* Processing the tool output::
@end menu

@noindent
The user has now specified the default switches he wants to use for the
external tool. Spawning the external tool can be done either from a menu
item, or as a result of a key press.

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

@c --------------------------------------------------------------------------
@node Chaining commands
@subsubsection Chaining commands
@c --------------------------------------------------------------------------

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

The command line for each of these commands can either be hard-coded in the
customization file, or be the result of previous commands executed as part of
the same action. As GPS executes each command from the action in turn, it
saves its output on a stack as needed. If a command line contains a special
construct @code{%1}, @code{%2}@dots{} then these constructs will be replaced
by the result of respectively the last command executed, the previous from last
command, and so on. They are replaced by the returned value of the command, not
by any output it might have done to some of the consoles in GPS.

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

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

@smallexample
<?xml version="1.0" ?>
<quotes>
  <action name="test quotes">
    <shell lang="python">'-a -b -c'</shell>
    <external> echo with quotes: "%1"</external>
    <external> echo without quotes: %2</external/>
  </action>
</quotes>
@end smallexample

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

@c --------------------------------------------------------------------------
@node Saving open windows
@subsubsection Saving open windows
@c --------------------------------------------------------------------------

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

Since this command aborts when the user presses cancel, you can
simply put it in its own @code{<shell>} command, as in:

@smallexample
<?xml version="1.0" ?>
<save_children>
  <action name="test save children">
    <shell>MDI.save_all 0</shell>
    <external>echo Run unless Cancel was pressed</external>
  </action>
</save_children>
@end smallexample

@c --------------------------------------------------------------------------
@node Querying project switches
@subsubsection Querying project switches
@cindex get_tool_switches_as_string
@cindex get_tool_switches_as_list
@cindex get_attribute_as_string
@cindex get_attribute_as_list
@c --------------------------------------------------------------------------

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

@smallexample
help Project.get_attribute_as_string
help Project.get_attribute_as_list
@end smallexample

The following is a short example on how to query the switches for the tool
"Find" from the project, @xref{Tool example}. It first creates an object
representing the current project, then passes this object as the first
argument of the @code{get_tool_switches_as_string} command. The last external
command is a simple output of these switches

@smallexample
<?xml version="1.0" ?>
<find_switches>
  <action name="Get switches for Find">
    <shell>Project %p</shell>
    <shell>Project.get_tool_switches_as_string %1 Find </shell>
    <external>echo %1</external>
  </action>
</find_switches>
@end smallexample

The following example shows how something similar can be done from Python, in
a simpler manner. For a change, this function queries the Ada compiler
switches for the current project, and prints them out in the messages
window. The

@smallexample
<?xml version="1.0" ?>
<query_switches>
  <action name="Query compiler switches">
    <shell lang="python">GPS.Project("%p").get_attribute_as_list
      (package="compiler",
       attribute="default_switches",
       index="ada")</shell>
    <external>echo compiler switches= %1</external>
  </action>
</query_switches>
@end smallexample

@c --------------------------------------------------------------------------
@node Querying switches interactively
@subsubsection Querying switches interactively
@cindex input_dialog
@cindex yes_no_dialog
@c --------------------------------------------------------------------------

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

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

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

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

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

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

The following is a short example that queries the name of a directory and a
file name, and displays each in the Messages window.

@smallexample
<?xml version="1.0" ?>
<query_file>
  <action name="query file and dir">
    <shell lang="python">list=GPS.MDI.input_dialog \
      ("Please enter directory and file name", "Directory", "File")</shell>
    <shell lang="python">print ("Dir=" + list[0], "File=" + list[1])</shell>
    </shell>
  </action>
</query_file>
@end smallexample

@c --------------------------------------------------------------------------
@node Redirecting the command output
@subsubsection Redirecting the command output
@cindex output
@c --------------------------------------------------------------------------

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

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

@table @code
@item "none"
The output of the command, as well as the text of the command itself, will not
be shown to the user at all.

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

@item other values
A new window is created, with the title given by the attribute. If such
a window already exists, it is cleared up before any of the command in the
chain is executed. The output of the command, as well
as the text of the command itself, are sent to this new window.
@end table

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

@smallexample
<?xml version="1.0" ?>
<ls>
  <action name="ls current directory" output="default output" >
     <shell output="Current directory" >pwd</shell>
     <external output="Current directory contents" >/bin/ls</external>
  </action>
</ls>
@end smallexample

@c --------------------------------------------------------------------------
@node Processing the tool output
@subsubsection Processing the tool output
@c --------------------------------------------------------------------------

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

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

@enumerate
@item Parsing error messages
@cindex Locations.parse

External tools can usually display error messages for the user that
are associated with specific files and locations in these files. This is for
instance the way the GPS builder itself analyzes the output of @code{make}.

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

@smallexample
file:line: message
file:line:column: message
@end smallexample

Please refer to the online help for this command to get more information
(by e.g. typing @code{help Locations.parse} in the GPS Shell).

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

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

@smallexample
<?xml version="1.0" ?>
<make>
  <action name="make example" >
     <external>make</external>
     <on-failure>
        <shell>Locations.parse """%1 """ make_example</shell>
     </on-failure>
  </action>
</make>
@end smallexample

@item Auto-correcting errors
@cindex Codefix.parse

GPS has support for automatically correcting errors for some of the languages.
You can get access to this auto-fixing feature through the @code{Codefix.parse}
shell command, which takes the same arguments as for @code{Locations.parse}.

This will automatically add pixmaps to the relevant entries in the location
window, and therefore @code{Locations.parse} should be called first prior to
calling this command.

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

@cindex Codefix.errors
@cindex CodefixError.fix
@cindex CodefixError.possible_fixes
If support for python is enabled, you can also manipulate the fixable errors
for a given session.
To do so, you must first get a handle on that section, as shown in the example
below. You can then get the list of fixable errors through the @code{errors}
command.

Each error is of the class @code{CodefixError}, which has one important
method @code{fix} which allows you to perform an automatic fixing for that
error. The list of possible fixes is retrieved through @code{possible_fixes}.

@smallexample
print GPS.Codefix.sessions ()
session = GPS.Codefix ("category")
errors  = session.errors ()
print errors [0].possible_fixes ()
errors [0].fix ()
@end smallexample

@end enumerate

@c ----------------------------------------------------------------
@node Customization examples
@section Customization examples
@c ----------------------------------------------------------------

@menu
* Menu example::
* Tool example::
@end menu

@c ----------------------------------------------------------------
@node Menu example
@subsection Menu example
@c ----------------------------------------------------------------

@noindent
This section provides a full example of a customization file.
It creates a top-level menu named @code{custom menu}.
This menu contains a menu item named @code{item 1}, which is associated to the
external command @code{external-command 1}, a sub menu named @code{other menu},
etc@dots{}

@smallexample
<?xml version="1.0"?>
<menu-example>
  <action name="action1">
    <external>external-command 1</external>
  </action>

  <action name="action2">
    <shell>edit %f</shell>
  </action>

  <submenu>
    <title>custom menu</title>
    <menu action="action1">
      <title>item 1</title>
    </menu>

    <submenu>
      <title>other menu</title>
      <menu action="action2">
        <title>item 2</title>
      </menu>
    </submenu>
  </submenu>
</menu-example>
@end smallexample

@c ----------------------------------------------------------------
@node Tool example
@subsection Tool example
@c ----------------------------------------------------------------

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

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

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

@smallexample
<?xml version="1.0" ?>
<toolexample>
  <tool name="Find" >
    <switches columns="2" >
      <title column="1" >Filters</title>
      <title column="2" >Actions</title>

      <spin label="Modified less than n days ago" switch="-mtime-"
            min="0" max="365" default="0" />
      <check label="Follow symbolic links" switch="-follow" />

      <check label="Print matching files" switch="-print" column="2" />
    </switches>
  </tool>

  <action name="action find">
    <shell>Project %p</shell>
    <shell>Project.get_tool_switches_as_string %1 Find </shell>
    <shell>MDI.input_dialog "Name of file to search" Filename</shell>
    <external>find . -name %1 %2</external>
  </action>

  <Submenu>
    <Title>External</Title>
     <menu action="action find">
       <Title>Launch find</Title>
    </menu>
  </Submenu>
</toolexample>
@end smallexample

@c --------------------------------------------------------------------
@node Scripting GPS
@section Scripting GPS
@cindex scripts
@c --------------------------------------------------------------------

@menu
* Scripts::
* Scripts and GPS actions::
* The GPS Shell::
* The Python Interpreter::
* Subprogram parameters::
* Python FAQ::
* Hooks::
@end menu

@c ---------------------------------------------------------------------
@node Scripts
@subsection Scripts
@c ---------------------------------------------------------------------

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

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

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

then press the @key{tab} key, which will list all the functions whose
name starts with "File".

A similar feature is available in the python console, which also
provides completion for all the standard python commands and modules.

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

See the section @ref{Customizing through XML and Python files} on how to bind key
shortcuts to shell commands.

@c --------------------------------------------------------------------
@node Scripts and GPS actions
@subsection Scripts and GPS actions
@cindex execute_action
@c --------------------------------------------------------------------

@noindent
There is a strong relationship between GPS actions, as defined in the
customization files (@pxref{Defining Actions}), and scripting languages

Actions can be bound to menus and keys through the customization files or
the @code{Edit->Key shortcuts} dialog.

These actions can execute any script command, @xref{Defining Actions}. This is
done through the @code{<shell>} XML tag.

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

Such calls are made through a call to @code{execute_action}, as in the
following example:

@smallexample
execute_action "Split horizontally"
@end smallexample

@smallexample
GPS.execute_action (action="Split horizontally")
@end smallexample

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

Some of the shell commands take subprograms as parameters. If you are using
the GPS shell, this means you have to pass the name of a GPS action. If
you are using Python, this means that you pass a subprogram,
@xref{Subprogram parameters}.

@c ------------------------------------------------------------------------
@node The GPS Shell
@subsection The GPS Shell
@cindex gps shell
@c ------------------------------------------------------------------------

@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 through XML and Python files}.

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

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

@smallexample
Locations.parse """%1 """ category_name
@end smallexample

@node The Python Interpreter
@subsection The Python Interpreter
@cindex python
@c ------------------------------------------------------------------------

@noindent
Python is an interpreted object-oriented language, created by Guido
Van Rossum. It is similar in its capabilities to languages such as
Perl, Tcl or Lisp. This section is not a tutorial on python
programming. See @url{http://docs.python.org/} to access the
documentation for the current version of python.

If python support has been enabled, the python shell is accessible through the
@code{Python} window at the bottom of the GPS window. You can also
display it by using the menu @file{Tools->Consoles->Python}.

The full documentation on what GPS makes visible through python is available
through the @code{/Help/Python extensions}.

The same example that was used to show the GPS shell follows, now using
python. As you can notice, the name of the commands is
similar, although they are not run exactly in the same
way. Specifically, GPS benefits from the object-oriented aspects of
python to create classes and instances of these classes.

In the first line, a new instance of the class Entity is created
through the @code{create_entity} function. Various methods can then be
applied to that instance, including @code{find_all_refs}, which lists
all references to that entity in the location window:

@smallexample
>>> e=GPS.Entity ("entity_name", "file_name.adb")
>>> e.find_all_refs()
@end smallexample

The screen representation of the classes exported by GPS to python has
been modified, so that most GPS functions will return an instance of a
class, but still display their output in a user-readable manner.

Python has extensive introspection capabilities. Continuing the
previous example, you can find what class @code{e} is an instance of
with the following command:

@smallexample
>>> help(e)
Help on instance of Entity:

<GPS.Entity instance>
@end smallexample

It is also possible to find all attributes and methods that can be
applied to @code{e}, as in the following example:

@smallexample
>>> dir (e)
['__doc__', '__gps_data__', '__module__', 'called_by', 'calls',
'find_all_refs']
@end smallexample

Note that the list of methods may vary depending on what modules were
loaded in GPS, since each module can add its own methods to any class.

In addition, the list of all existing modules and objects currently known
in the interpreter can be found with the following command:

@smallexample
>>> dir ()
['GPS', 'GPSStdout', '__builtins__', '__doc__', '__name__', 'e', 'sys']
@end smallexample

You can also load and execute python scripts with the @code{execfile} command,
as in the following example:

@smallexample
>>> execfile ("test.py")
@end smallexample

Python supports named parameters. Most functions exported by GPS define
names for their parameters, so that you can use this Python feature, and
make your scripts more readable. A notable exception to this rule are the
functions that take a variable number of parameters.
Using named parameters allows you to specify the parameters in any order
you wish, e.g:

@smallexample
>>> e=GPS.Entity (name="foo", file="file.adb")
@end smallexample

@subsection Python modules

On startup, GPS will automatically import (with python's @code{import}
command) all the files with the extension @file{.py} found in the directory
@file{$HOME/.gps/plug-ins}, the directory @file{$prefix/share/gps/plug-ins}
 or in the directories pointed to by
@file{GPS_CUSTOM_PATH}. These files are loaded only after all standard
GPS modules have been loaded, as well as the custom files, and before
the script file or batch commands specified on the command lines with
the @code{--eval} or @code{--load} switches.

As a result, one can use the usual GPS functions exported to python in these
startup scripts. Likewise, the script run from the command line can use
functions defined in the startup files.

Since the @code{import} command is used, the functions defined in this
modules will only be accessible by prefixing their name by the name of the
file in which they are defined. For instance if a file @file{mystartup.py}
is copied to the startup directory, and defines the function @code{func},
then the latter will be accessible in GPS through @code{mystartup.func}.

Python's own mechanism for loading files at startup (the environment
variable @code{PYTHONSTARTUP}) is not suitable for use within the context
of GPS. When python is loaded by GPS, the GPS module itself is not yet
available, and thus any script that depends on that module will fail to
load correctly. Instead, copy your script to one of the plug-ins directories,
as documented above.

If you are writing a set of python scripts that other people will use,
you need to provide several things:

@itemize
@item The python files themselves. This is a set of @file{.py} files, which
 the user should install in the @file{plug-ins} directory.

@item Optionally: an XML file with the format described in the customization section
 of this documentation. This XML file should create a set of actions,
 through the @code{<action>} tag, exported to the user. This allows him
 to either create menus to execute these commands or to bind them to special
 key shortcuts. The menus can be created directly in python, with the
 @code{GPS.Menu} class. The same XML can in fact be directly embedded in the
 python file itself and executed through @code{GPS.parse_xml}.
@end itemize

The following example defines a python command that inserts a line full of
dashes ('-') at the current cursor location. This command is associated with
the key binding @key{control-c n}, and can be distributed as a single XML
file.

@smallexample
# This code can be stored in a file test.py in $HOME/.gps/plug-ins
from GPS import *

def add_dashes_line():
   Editor.replace_text (current_context().file().name(),
                        current_context().location().line(),
                        current_context().location().column(),
                        "--------------------------------", 0, 0)
GPS.parse_xml ("""
   <action name="dashes line">
      <shell lang="python">test.add_dashes_line()</shell>
      <context>Source editor</context>
   </action>
   <key action="dashes line">control-c n</key>
""")

@end smallexample

Several complex examples are provided in the GPS distribution, in the
directory @file{examples/python}. These are modules that you might want
to use for your own GPS, but more important that will show how GPS can
be extended from Python.

If your script doesn't do what you expect it to do, there are several
ways to debug it, among which the easiest is probably to add some "print"
statements. Since some output of the scripts is sometimes hidden by GPS
(for instance for interactive commands), you might not see this output.

In this case, you can reuse the tracing facility embedded in GPS itself.
Modify the file @file{$HOME/.gps/traces.cfg}, and add the following line:

@smallexample
PYTHON.OUT=yes
@end smallexample

This will include the python traces as part of the general traces available
in the file @file{$HOME/.gps/log}. Note that it may slow down GPS if there is
a lot of output to process.

@c --------------------------------------------------------------------
@node Subprogram parameters
@subsection Subprogram parameters
@cindex subprogram parameters
@c --------------------------------------------------------------------

@noindent
A few of the functions exported by GPS in the GPS shell or in python expect
a subprogram as a parameter.

This is handled in different ways depending on what language your are using:

@itemize @bullet
@item GPS shell

It isn't possible to define new functions in the GPS shell. However, this
concept is similar to the GPS actions (@pxref{Defining Actions}), which
allow you to execute a set of commands and launch external processes.

Therefore, a subprogram parameter in the GPS shell is a string, which is the
name of the action to execute.

For instance, the following code defines the action "on_edition",
which is called every time a new file is edited. The action is defined
in the shell itself, although this could be more conveniently done in
a separate customization file.

@smallexample
parse_xml """<action name="on_edition">
             <shell>echo "File edited"</shell></action>"""
Hook "file_edited"
Hook.add %1 "on_edition"
@end smallexample

@item Python

Python of course has its own notion of subprogram, and GPS is fully compatible
with it. As a result, the syntax is much more natural than in the GPS shell.
The following example has the same result as above:

@smallexample
import GPS
def on_edition(self, *arg):
  print "File edited"
GPS.Hook ("file_edited").add (on_edition)
@end smallexample

Things are in fact slightly more complex if you want to pass methods
as arguments. Python has basically three notions of callable
subprograms, detailed below. The following examples all create a combo
box in the toolbar, which calls a subprogram whenever its value is
changed. The documentation for the combo box indicates that the
callback in this case takes two parameters:

@itemize -
@item The instance of the combo
@item The current selection in the combo box
@end itemize

The first parameter is the instance of the combo box associated with
the toolbar widget, and, as always in python, you can store your own
data in the instance, as shown in the examples below.

Here is the description of the various subprograms:

@itemize @bullet
@item Global subprograms

These are standard subprograms, found outside class definitions. There
is no implicit parameter in this case. However, if you need to pass
data to such a subprogram, you need to use global variables

@smallexample
import GPS

my_var = "global data"

def on_changed (combo, choice):
   global my_var
   print "on_changed called: " + \
      my_var + " " + combo.data + " " + choice

combo = GPS.Combo \
  ("name", label="name", on_changed=on_changed)
GPS.Toolbar().append (combo)
combo.data = "My own data"
@end smallexample

@item Unbound methods

These are methods of a class. You do not specify, when you pass the
method in parameter to the combo box, what instance should be passed
as its first parameter. Therefore, there is no extra parameter either.

Note however than whatever class the method is defined in, the first
parameter is always an instance of the class documented in the GPS
documentation (in this case a GPS.Combo instance), not an
instance of the current class.

In this first example, since we do not have access to the instance of
MyClass, we also need to store the global data as a class
component. This is a problem if multiple instances of the class can
be created.

@smallexample
import GPS
class MyClass:
   my_var = "global data"
   def __init__ (self):
      self.combo = GPS.Combo \
         ("name", label="name", on_changed=MyClass.on_changed)
      GPS.Toolbar().append (self.combo)
      self.combo.data = "My own data"

   def on_changed (combo, choice):
      ## No direct access to the instance of MyClass.
      print "on_changed called: " + \
         MyClass.my_var + " " + combo.data + " " + choice

MyClass()
@end smallexample

As the example above explains, there is no direct access to MyClass
when executing on_changed. An easy workaround is the following, in
which the global data can be stored in the instance of MyClass,
and thus be different for each instance of MyClass.

@smallexample
import GPS
class MyClass:
   def __init__ (self):
      self.combo = GPS.Combo \
         ("name", label="name", on_changed=MyClass.on_changed)
      GPS.Toolbar().append (self.combo)
      self.combo.data = "My own data"
      self.combo.myclass = self   ## Save the instance
      self.my_var = "global data"

   def on_changed (combo, choice):
      print "on_changed called: " + \
         combo.myclass.my_var + " " + combo.data + " " + choice

MyClass()
@end smallexample

@item Bound methods

The last example works as expected, but is not convenient to use. The
solution here is to use a bound method, which is a method for a
specific instance of a class. Such a method always has an extra first
parameter, set implicitly by Python or GPS, which is the instance of
the class the method is defined in.

Notice the way we pass the method in parameter to append(), and the
extra third argument to on_changed in the example below.

@smallexample
import GPS
class MyClass:
   def __init__ (self):
      self.combo = GPS.Combo \
         ("name", label="name", on_changed=self.on_changed)
      GPS.Toolbar().append (self.combo)
      self.combo.data = "My own data"
      self.my_var = "global data"

   def on_changed (self, combo, choice):
      # self is the instance of MyClass specified in call to append()
      print "on_changed called: " + \
         self.my_var + " " + combo.data + " " + choice

MyClass()
@end smallexample

It is often convenient to use the object-oriented approach when writing
python scripts. If for instance you want to spawn an external process,
GPS provides the @code{GPS.Process} class. When you create an instance,
you specify a callback to be called when some input is made available
by the process. Matching the above example, the code would look something
like:

@smallexample
class MyClass:
  def __init__ (self):
     self.process = GPS.Process
         ("command_line", on_match = self.on_match)

  def on_match (self, process, matched, unmatched);
     print "Process output: " + unmatched + matched + "\n"
@end smallexample

A more natural approach, rather than having a class that has a process
field, is to directly extend the @code{GPS.Process} class, as in:

@smallexample
class MyClass (GPS.Process):
  def __init__ (self):
     GPS.Process.__init__ \
        (self, "command_line", on_match = self.on_match)

  def on_match (self, matched, unmatched);
     print "Process output: " + unmatched + matched + "\n"
@end smallexample

Any command that can be used on a process (such as @code{send}) can then
directly be used on instances of MyClass.

There is one non-obvious improvement in the code above: the @code{on_match}
callback has one less parameter. What happens is the following: as per
the documentation of @code{GPS.Process.__init__}, GPS gives three arguments
to its @code{on_match} callback: the instance of the process (@code{process}
in the first example above), the string that matched the regular expression,
and the string before that match.

In the first example above, we are passing @code{self.on_match}, ie a
bound method, as a callback. That tells python that it should automatically,
and transparently, add an extra first parameter when calling
@code{MyClass.on_match}, which is @code{self}. This is why the first example
has four parameters to @code{on_match}.

However, the second example only has three parameters, because GPS has
detected that @code{self} (the instance of @code{MyClass}) and the
instance of @code{GPS.Process} are the same in this case. Thus it doesn't
add an extra parameter (@code{self} and @code{process} would have been
the same).

@end itemize

@end itemize

@c ------------------------------------------------------------------------
@node Python FAQ
@subsection Python FAQ
@cindex python
@c ------------------------------------------------------------------------

@noindent
This section lists some of the problems that have been encountered while using
Python inside GPS. This is not a general Python discussion.

@menu
* Hello World! in python::
* Spawning external processes::
* Redirecting the output of spawned processes::
* Contextual menus on object directories only::
* Redirecting the output to specific windows::
* Reloading a python file in GPS::
* Printing the GPS Python documentation::
* Automatically loading python files at startup::
* Hiding contextual menus::
* Creating custom graphical interfaces::
@end menu

@c -------------------------------------------
@node Hello World! in python
@subsubsection Hello World! in python

Writing a python script to interact with GPS is very simple. Here we show
how to create a new menu in GPS that when clicked, diplays a dialog saying
the famous ``Hello World!''.

Here is the code that you need to put in hello_world.py:

@smallexample
import GPS

def hello_world (self):
   GPS.MDI.dialog ("Hello World!")

GPS.Menu.create ("/Help/Hello World!", on_activate=hello_world)
@end smallexample

In order to use this plug-in, you can launch GPS with the following command
line:

@smallexample
$ gps --load=python:hello_world.py
@end smallexample

If would want the plug-in to be loaded everytime you launch GPS without having
to specify it on the command line, you should copy hello_world.py to your
@code{$HOME/.gps/plug-ins/} directory or @code{%USERPROFILE%\.gps\} under
Windows.

Alternatively, you can add the directory in which you plug-in is located to
you @code{GPS_CUSTOM_PATH} environment variable.
For a description of the various environment variables used by GPS,
@pxref{Environment Variables}.

@c -------------------------------------------
@node Spawning external processes
@subsubsection Spawning external processes

There exist various solutions to spawn external processes from a script:

@itemize
@item Use the functionalities provided by the @code{GPS.Process} class
@item Execute a GPS action through @code{GPS.execute_action}.

This action should have an @code{<external>} XML node indicating how to
launch the process

@item Create a pipe and execute the process with @code{os.popen()} calls

This solution doesn't provide a full interaction with the process, though.

@item Use a standard expect library of Python

The use of an expect library may be a good solution. There are various python
expect libraries that already exist.

These libraries generally try to copy the parameters of the standard @code{file}
class. They may fail doing so, as GPS's consoles do not fully emulate all
the primitive functions of that class (there is no file descriptor for
instance).

When possible, it is recommended to use one of the methods above instead.
@end itemize

@c -------------------------------------------
@node Redirecting the output of spawned processes
@subsubsection Redirecting the output of spawned processes

In general, it is possible to redirect the output of any Python script to
any GPS window (either an already existing one, or creating one automatically),
through the @code{"output"} attribute of XML configuration files.

However, there is a limitation in python that the output of processes spawned
through os.exec() or os.spawn() is redirected to the standard output, and not
to the usual python output that GPS has overriden.

There are two solutions for this:
@itemize @bullet
@item Execute the external process through a pipe

The output of the pipe is then redirected to Python's output, as in:

@smallexample
import os, sys
def my_external():
   f = os.popen ('ls')
   console = GPS.Console ("ls")
   for l in f.readlines():
      console.write ('   ' + l)
@end smallexample

This solution allows you, at the same time, to modify the output, for instance
to indent it as in the example above.

@item Execute the process through GPS

You can go through the process of defining an XML customization string for
GPS, and execute your process this way, as in:

@smallexample
GPS.parse_xml ("""
   <action name="ls">
     <external output="output of ls">ls</external>
   </action>""")

def my_external():
   GPS.execute_action ("ls")
@end smallexample

This solution also allows you to send the output to a different window than the
rest of your script. But you cannot filter or modify the output as in the
first solution.

@end itemize

@c ----------------------------------------------
@node Contextual menus on object directories only
@subsubsection Contextual menus on object directories only

The following filter can be used for actions that can only execute in the
Project View, and only when the user clicks on an object directory. The
contextual menu entry will not be visible in other contexts

@smallexample
<?xml version="1.0" ?>
<root>
   <filter name="object directory"
           shell_cmd="import os.path; os.path.samefile (GPS.current_context().project().object_dirs()[0],GPS.current_context().directory())"
           shell_lang="python"
           module="Explorer" />

   <action name="Test on object directory">
      <filter id="object directory" />
      <shell>echo "Success"</shell>
   </action>

   <contextual action="Test on object directory" >
      <Title>Test on object directory</Title>
   </contextual>
</root>
@end smallexample

Another example would be to have a filter so that the contextual menu only
appears when on a project node in the Project View. Using @code{%P} in your
command is not enough, since the current context when you click on a file
or directory also contain information about the project this file or directory
belongs to. Thus this implicit filter will not be enough to hide your
contextual menu.

As a result, you need to do a slightly more complex test, where you check that
the current context doesn't contains information on directories (which will
disable the contextual menu for directories, files and entities). Since the
command uses @code{%P}, GPS garantees that a project is available.

We'll implement this contextual menu in a Python file, called
@file{filters.py}.

@smallexample
import GPS
def on_project():
try:
GPS.current_context().directory()
return False
except:
return True

GPS.parse_xml ("""
<action name="test_filter">
<filter module="Explorer"
     shell_lang="python"
     shell_cmd="filters.on_project()" />
<shell>echo current project is %P</shell>
</action>
<contextual action="test_filter">
<title>Print current project</title>
</contextual>""")
@end smallexample

The example above shows the flexibility of filters, since you can pretty much
do anything you wish through the shell commands. However, it is complex to
write for such a simple filter. Luckily, GPS provides a predefined filter
just for that purpose, so that you can write instead, in an XML file:

@smallexample
<action name="test_filter" >
<filter id="Explorer_Project_Node" />
<shell>echo current project is %P</shell>
</action>
@end smallexample

@c  --------------------------------------------------------
@node Redirecting the output to specific windows
@subsubsection Redirecting the output to specific windows

By default, the output of all python commands is displayed in the Python
console. However, you might want in some cases to create other windows in
GPS for this output. This can be done in one of two ways:

@itemize @bullet
@item Define a new action

If the whole output of your script should be redirected to the same window,
or if the script will only be used interactively through a menu or a key
binding, the easiest way is to create a new XML action, and redirect the
output, as in

@smallexample
<?xml version="1.0" ?>
<root>
  <action name="redirect output" output="New Window">
     <shell lang="python">print "a"</shell>
  </action>
</root>
@end smallexample

All the various shell commands in your action can be output in a different
window, and this also applies for the output of external commands.

@item Explicit redirection

If, however, you want to control in your script where the output should be
sent, for instance if you can't know that statically when you write your
commands, you can use the following code:

@smallexample
sys.stdin = sys.stdout = GPS.Console ("New window")
print "foo"
print (sys.stdin.read ())
sys.stdin = sys.stdout = GPS.Console ("Python")
@end smallexample

The first line redirect all input and output to a new window, which is
created if it doesn't exist yet. Note however that the output of stderr
is not redirected, and you need to explicitely do it for @code{sys.stderr}.

The last line restore the default Python console. You must do this
at the end of your script, or all scripts will continue to use the new
consoles.

You can alternatively create separate objects for the output, and use them
in turn:

@smallexample
my_out  = GPS.Console ("New Window")
my_out2 = GPS.Console ("New Window2")

sys.stdout=my_out
print "a"
sys.stdout=my_out2
print "b"
sys.stdout=GPS.Console ("Python")
@end smallexample

The parameter to the constructor @code{GPS.Console} indicates whether any
output sent to that console should be saved by GPS, and reused for the
@code{%1}, @code{%2}, @dots{} parameters if the command is executed in a
GPS action. That should generally be 1, except for stderr where it should
be 0.
@end itemize

@c -------------------------------------------
@node Reloading a python file in GPS
@subsubsection Reloading a python file in GPS

After you have made modification to a python file, you might want to
reload it in GPS. This requires careful use of python commands.

Here is an example. Lets assume you have a python file (@file{"mymod.py"})
which contains the following:

@smallexample
GPS.parse_xml ("""
   <action name="my_action">
      <shell lang="python">mymod.myfunc()</shell>
   </action>""")

def myfunc():
   print "In myfunc\n"
@end smallexample

As you can guess from this file, it defines an action "my_action", that you
can for instance associate with a keybinding through the Edit->Key shortcuts
menu.

If this file has been copied in one of the @file{plug-ins} directories,
it will be automatically loaded at startup.

Notice that the function @code{myfunc} is thus found in a separate namespace,
with the name @code{mymod}, same as the file.

If you decide, during your GPS session, to edit this file and have the
function print "In myfunc2" instead, you then have to reload the file by
typing the following command in the Python console:

@smallexample
> execfile ("HOME/.gps/plug-ins/mymod.py", mymod.__dict__)
@end smallexample

The first parameter is the full path to the file that you want to reload.
The second argument is less obvious, but indicates that the file should be
reloaded in the namespace @code{mymod}.

If you omit the optional second parameter, Python will load the file, but
the function @code{myfunc} will be defined in the global namespace, and thus
the new definition is accessible through

@smallexample
> myfunc()
@end smallexample

Thus, the key shortcut you had set, which still executes @code{mymod.myfunc()}
will keep executing the old definition.

By default, GPS provides a contextual menu when you are editing a Python
file. This contextual menu (Python->Reload module) will take care of all
the above details.

@c -------------------------------------------
@node Printing the GPS Python documentation
@subsubsection Printing the GPS Python documentation

The python extension provided by GPS is fully documentation in this
manual and a separate manual accessible through the Help menu in GPS.

However, this documentation is provided in HTML, and might not be the
best suitable for printing, if you wish to do so.

The following paragraph explains how you can generate your own documentation
for any python module, including GPS, and print the result.

@smallexample
import pydoc
pydoc.writedoc (GPS)
@end smallexample

In the last comamnd, @code{GPS} is the name of the module that you want
to print the documentation for.

These commands generate a @file{.html} file in the current directory.

Alternatively, you can generate a simple text file with

@smallexample
e=file("./python_doc", "w")
e.write (pydoc.text.document (GPS))
e.flush()
@end smallexample

This text file includes bold characters by default. Such bold characters
are correctly interpreted by tools such as @file{a2ps} which can be used
to convert the text file into a postscript document.

@c -------------------------------------------
@node Automatically loading python files at startup
@subsubsection Automatically loading python files at startup

@noindent
At startup, GPS will automatically load all python files found in
the directories @file{share/gps/plug-ins} and
@file{$HOME/.gps/plug-ins}.

In addition, python files located under
@file{<prefix>/share/gps/python} can be imported (using the @code{import}
command) by any python script.

You can also set the @code{PYTHONPATH} environment variable to add other
directories to the python search path.

@c --------------------------------------------------------------------
@node Hiding contextual menus
@subsubsection Hiding contextual menus
@cindex contextual menus

@noindent
GPS provides most of its tools through contextual menus, accessed by right
clicking in various parts of GPS. Due to the number of tools provided by GPS,
these contextual menus tend to be big, and you might want to control what
should be displayed in them. There are several ways to control this:

@itemize @bullet
@item Define appropriate filters for your actions

If you are creating your own contextual menus through customization files and
XML, these menus are associated with actions (@code{<action>}) that you have
created yourself most of the time. In this case, you need to define filters
appropriately, through the @code{<filter>} tag, to decide when the action
is relevant, and therefore when the contextual menu should be displayed.

@item Use shell commands to hide the menus

If you want to control the visibility of predefined contextual menus, or
for menus where you cannot easily modify the associated filter, you can
use shell and python commands to hide the menu entry. For this, you will
need to find out the name of the menu, which can be done by checking the
list returned by @code{GPS.Contextual.list()} and using the most likely
entry. This name is also the value of the @code{<title>} tag for contextual
menus that you have created yourself. Using this name, you can then disable
the contextual menu by executing:

@smallexample
 GPS.Contextual ("name").hide()
@end smallexample

in the python console

@end itemize

@c --------------------------------------------------------------------
@node Creating custom graphical interfaces
@subsubsection Creating custom graphical interfaces
@cindex pygtk

@noindent
GPS is based on the Gtk+ graphical toolkit, which is available under many
platforms and for many programming languages.

In particular, GPS comes with pygtk, a python binding to Gtk+.
Using pygtk, you will be able to create your own dialogs and graphical
windows using the python capabilities provided by GPS.

See the menu @code{Help->Python Extensions}, in particular the @code{GPS.MDI}
documentation, for a sample of code on how to create your own graphical
interfaces and integrate them in GPS.

@c --------------------------------------------------------------------
@node Hooks
@subsection Hooks
@cindex hooks
@c --------------------------------------------------------------------

@noindent
A @b{hook} is a named set of commands to be executed on particular occasions
as a result of user actions in GPS.

GPS and its various modules define a number of standard hooks, which are
called for instance when a new project is loaded, when a file is edited, and
so on. You can define your own commands to be executed in such cases.

@cindex hooks, Hook.list
@cindex hooks, Hook.describe
You can find out the list of hooks that GPS currently knows about by calling
the @b{Hook.list} function, which takes no argument, and returns a list of
hook names that you can use. More advanced description for each hook is
available through the @code{Help->Python Extensions}.

@smallexample
GPS> Hook.list
project_changed
open_file_action_hook
preferences_changed
[...]

Python> GPS.Hook.list()
@end smallexample

@cindex hooks, type
The description of each hooks includes a pointer to the type of the hook, that
is what parameters the subprograms in this hook will receive. For instance:

@cindex hooks, Hook.list_types
The list of all known hook types can be found through the @b{Hook.list_types}
command. This takes no argument and returns a list of all known types of hooks.
As before, you can more information for each of these type through a call to
@b{Hook.describe_type}.

@c ----------------------------------
@subsubsection Adding commands to hooks
@c ----------------------------------

@noindent
You can add your own command to existing hooks through a call to the
@b{Hook.add} command. Whenever the hook is executed by GPS or another script,
your command will also be executed, and will be given the parameters that
were specified when the hook is run. The first parameter is always the name
of the hook being executed.

This @b{Hook.add} applies to an instance of the hook class, and takes one
parameter, the command to be executed. This is a subprogram parameter (@pxref{Subprogram parameters}).

@itemize @bullet
@item GPS shell

The command can be any GPS action (@pxref{Defining Actions}). The arguments for
the hook will be passed to the action, and are available as $1, $2, @dots{};
In the following example, the message "Just executed
the hook: project_changed" will be printed in the Shell console. Note that we
are defining the action to be executed inline, but this could in fact be
defined in a separate XML customization file for convenience.

@smallexample
GPS> parse_xml """<action name="my_action"><shell>echo "Just executed the hook"</shell></action_name>"""
GPS> Hook project_changed
GPS> Hook.add %1 "my_action"
@end smallexample

@item Python

The command must be a subprogram to execute. The arguments for the
hook will be passed to this subprogram. In the following example, the
message "The hook project_changed was executed by GPS" will be displayed in the
Python console whenever the project changes.

@smallexample
def my_callback (name):
    print "The hook " + name + " was executed by GPS"
GPS.Hook ("project_changed").add (my_callback)
@end smallexample

@end itemize

The example above shows the simplest type of hook, which doesn't take any
argument. However, most hooks receive several parameters. For instance, the
hook "file_edited" receives the file name as a parameter.

@itemize @bullet
@item GPS shell

The following code will print the name of the hook ("file_edited") and the
name of the file in the shell console every time a file is open by GPS.
@smallexample
GPS> parse_xml """<action name="my_action"><shell>echo name=$1 file=$2</shell></action>"""
GPS> Hook "file_edited"
GPS> Hook.add %1 "my_action"
@end smallexample

@item Python

The following code prints the name of the file being edited by GPS in the
python console whenever a new editor is opened. The second argument is of type
GPS.File.

@smallexample
def my_file_callback (name, file):
    print "Editing " + file.name()
GPS.Hook ("file_edited").add (my_file_callback)
@end smallexample

@end itemize

@c ----------------------------------
@subsubsection Action hooks
@cindex hooks, action_hooks
@cindex hooks, open_file_action_hook
@c ----------------------------------

@noindent
Some hooks have a special use in GPS. Their name always ends with
"_action_hook".

As opposed to the standard hooks described in the previous section, the
execution of the action hooks stops as soon as one of the subprograms returns
a True value ("1" or "true"). The subprograms associated with that hook are
executed one after the other. If any such subprogram knows how to act for that
hook, it should do the appropriate action and return "1".

Other action hooks expect a string as a return value instead of a boolean. The
execution will stop when a subprogram returns a non-empty string.

This mechanism is used extensively by GPS internally. For instance, whenever
a file needs to be opened in an editor, GPS executes the
"open_file_action_hook" hook to request its editing. Several modules are
connected to that hook.

One of the first modules to be executed is the external editor module. If the
user has chosen to use an external editor, this module will simply spawn
Emacs or the external editor that the user has selected, and return 1. This
immediately stops the execution of the "open_file_action_hook".

However, if the user doesn't want to use external editors, this module will
return 0. This will keep executing the hook, and in particular will execute the
source editor module, which will always act and open an editor internally in
GPS.

This is a very flexible mechanism. In your own script, you could choose to
have some special handling for files with a ".foo" extension for instance. If
the user wants to open such a file, you would spawn for instance an external
command (say "my_editor") on this file, instead of opening it in GPS.

This is done with a code similar to the following

@smallexample
from os.path import *
import os
def my_foo_handler (name, file, line, column, \
                    column_end, enable_nav, new_file, reload):
    if splitext (file.name())[1] == ".foo":
        os.spawnv \
           (os.P_NOWAIT, "/usr/bin/emacs", ("emacs", file.name()))
        return 1   ## Prevent further execution of the hook
    return 0  ## Let other subprograms in the hook do their job

GPS.Hook ("open_file_action_hook").add (my_foo_handler)
@end smallexample

@c --------------------------------------------------------------------
@subsubsection Running hooks
@cindex hooks, Hook.run
@c --------------------------------------------------------------------

@noindent
Any module in GPS is responsible for running the hooks when appropriate.
Most of the time, the subprograms exported by GPS to the scripting languages
will properly run the hook. But you might also need to run them in your own
scripts.

As usual, this will result in the execution of all the functions bound to
that hook, whether they are defined in Ada or in any of the scripting
languages.

This is done through the @b{Hook.run} command. This applies to an instance
of the Hook class, and a variable number of arguments
These must be in the right order and of the right type
for that specific type of hook.

If you are running an action hook, the execution will stop as usual as soon
as one of the subprograms return a True value.

The following example shows how to run a simple hook with no parameter, and
a more complex hook with several parameters. The latter will in fact request
the opening of an editor for the file in GPS, and thus has an immediately
visible effect on the interface. The file is opened at line 100. See the
description of the hook for more information on the other parameters.

@smallexample
GPS.Hook ("project_changed").run()
GPS.Hook ("open_file_action_hook").run \
              (GPS.File ("test.adb"), 100, 1, 0, 1, 1, 1)
@end smallexample

@c --------------------------------------------------------------------
@subsubsection Creating new hooks
@cindex hooks, creating
@cindex hooks, Hook.register
@c --------------------------------------------------------------------

@noindent
The list of hooks known to GPS is fully dynamic. GPS itself declares a
number of hooks, mostly for its internal use although of course you can
also connect to them.

But you can also create your own hooks to report events happening in your
own modules and programs. This way, any other script or GPS module can
react to these events.

Such hooks can either be of a type exported by GPS, which constraints the
list of parameters for the callbacks, but make such hooks more portable and
secure; or they can be of a general type, which allows basically any kind
of parameters. In the latter case, checks are done at runtime to ensure that
the subprogram that is called as a result of running the hook has the right
number of parameters. If this isn't the case, GPS will complain and display
error messages. Such general hooks will also not pass their parameters to
other scripting languages.

Creating new hooks is done through a call to @b{Hook.register}. This function
takes two arguments: the name of the hook you are creating,
and the type of the hook.

The name of the hook is left to you. Any character is allowed in that name,
although using only alphanumerical characters is recommended.

The type of the hook must be one of the following:

@itemize @bullet
@item "" (the empty string)

This indicates that the hook doesn't take any argument. None should be given
to @b{Hook.run}, and none should be
expected by the various commands connected to that hook, apart from
the hook name itself.

@item one of the values returned by @b{Hook.list_types}

This indicates that the hook is of one of the types exported by GPS itself. The
advantage of using such explicit types as opposed to "general" is that GPS
is able to make more tests for the validity of the parameters. Such hooks can
also be connected to from other scripting languages.

@item "general"

This indicates that the hook is of the general type that allows any number of
parameter, of any type. Other scripts will be able to connect to it, but will
not be executed when the hook is run if they do not expect the same number of
parameters that was given to @b{Hook.run}. Other scripts in other language will
only receive the hook name in parameter, not the full list of parameters.

@end itemize

A small trick worth noting: if the command bound to a hook doesn't have the
right number of parameters that this hook provide, the command will not be
executed and GPS will report an error. You can make sure that your command
will always be executed by either giving default values for its parameter, or
by using python's syntax to indicate a variable number of arguments.

This is especially useful if you are connecting to a "general" hook, since you
do not really know in advance how many parameters the call of @b{Hook.run} will
provide.

@smallexample
## This callback can be connected to any type of hook
def trace (name, *args):
   print "hook=" + name

## This callback can be connected to hooks with one or two parameters
def trace2 (name, arg1, arg2=100):
   print "hook=" + str (arg1) + str (arg2)

Hook.register ("my_custom_hook", "general")
Hook ("my_custom_hook").add (trace2)
Hook ("my_custom_hook").run (1, 2) ## Prints 1 2
Hook ("my_custom_hook").run (1)    ## Prints 1 100
@end smallexample

@c --------------------------------------------------------------------
@node Adding support for new Version Control Systems
@section Adding support for new Version Control Systems
@cindex generic_vcs
@c --------------------------------------------------------------------

@menu
* Custom VCS interfaces::
* Describing a VCS::
* Implementing VCS actions::
@end menu

@node Custom VCS interfaces
@subsection Custom VCS interfaces

@noindent
The Version Control interface in GPS can be customized, either to
refine the behavior of the existing system and adapt it to specific
needs, or to add support for other Version Control systems.

Custom VCS interfaces are defined entirely through XML files. Those
files are read in the same location as all the other XML
customizations that GPS offers. See @ref{Customizing through XML and Python files} for a
complete description.

There are two steps to follow when creating a custom VCS
interface. The first step is to describe the VCS itself, and the
second step is to implement actions corresponding to all the
operations that this VCS can perform. The following two sections
(@ref{Describing a VCS} and @ref{Implementing VCS actions}) describe
those steps.

GPS is distributed with XML files describing the interfaces to
ClearCase, CVS and Subversion. These XML files are located in the directory
@code{share/gps/plug-ins} in the GPS installation, and can be used as a
reference for implementing new custom VCS interfaces.

@node Describing a VCS
@subsection Describing a VCS

@menu
* The VCS node::
* Associating actions to operations::
* Defining revision information::
* Defining status::
* Output parsers::
@end menu

@node The VCS node
@subsubsection The VCS node

@noindent
The @code{vcs} node is the toplevel node which contains the
description of the general behavior expected from the VCS. It has the
following attributes:

@table @code
@item name
The attribute @code{name} indicates the identifier of the VCS. The
casing of this name is important, and the same casing must be used in
the project files.

@item absolute_names
The attribute @code{absolute_names} indicates the behavior of the
VCS relative to file names, and can take the values @code{TRUE} or
@code{FALSE}. If it is set to @code{TRUE}, it means that all
commands in the VCS will work on absolute file names. If it set to
@code{FALSE}, it means that all actions work on base file names, and
that GPS will move to the appropriate directory before executing an
action.

@item group_queries_by_directory
The attribute @code{group_queries_by_directory} indicates that, when querying
status for all the source files in a directory, a query for the directory
should be launched, instead of launching a query for multiple files.
This operation is faster on some Version Control systems. By default, this
is set to @code{FALSE}.

@item ignore_file
The attribute @code{ignore_file} specifies the name of the file used
by the VCS Explorer to get the list of files to ignore. By default for
the CVS mode this is set to @file{.cvsignore}.

@item atomic_commands
The attribute @code{atomic_commands} specifies if the VCS supports
atomicity and can take the values @code{TRUE} or @code{FALSE}. If it
is set to @code{TRUE} it means that the VCS supports atomic
commands. It is @code{FALSE} by default. This attribute is important
to trigger the activities group commit feature. See @xref{The VCS Activities}.

@item path_style
The attribute @code{path_style} specifies which kind of directory separator
is supported by the VCS and can take the values @code{UNIX},
@code{DOS}, @code{Cygwin} or @code{System_Default}. The later value is
the default value. With this attribute it is possible to control the
directory separator to use when specifying files to the VCS. For the
@code{Cygwin} case the drive is specified as @code{/cygdrive/<drive>}.

@item dir_sep
Alias for @code{path_style}, obsolescent.

@item commit_directory
The attribute @code{commit_directory} specifies if the VCS supports
commit on directories and can take the values @code{TRUE} or @code{FALSE}.
If it is set to @code{TRUE} it means that the VCS supports commit on
directories this is the case for @code{Subversion} for example.

@item administrative_directory
The attribute @code{administrative_directory} specifies the name of
the directory where the external VCS stores the local repository
information. For example for Subversion this is @file{.svn}. This
information is used when the project is setup to select automatically
the external VCS. @xref{Version Control System}.

@item require_log
The attribute @code{require_log} specifies if the VCS require a log
for the commit/add/delete actions. It can take the values @code{TRUE}
or @code{FALSE}. If it is set to @code{TRUE} GPS will ensure that
a log is created for each file. If it is set to @code{FALSE} GPS will
not ask for log, it is expected to be handled by the external VCS.
@end table

Note that to support group commit with shared log on GPS both
@code{absolute_name} and @code{atomic_commands} must be true. This is
the case for the Subversion VCS for example.

Here is an example, adapted to the use of CVS:

@smallexample
   <vcs name="Custom CVS" absolute_names="FALSE">

      (... description of action associations ...)
      (... description of supported status ...)
      (... description of output parsers ...)

   </vcs>
@end smallexample

@node Associating actions to operations
@subsubsection Associating actions to operations

@noindent
GPS knows about a certain set of predefined ``operations'' that a VCS
can perform. The user can decide to implement some of them - not
necessarily all of them - in this section.

The following node is used to associate a predefined operation to an
action:

@smallexample
   <OPERATION  action="ACTION_LABEL" label="NAME OF OPERATION" />
@end smallexample

Where:
@table @samp
   @item OPERATION
is the name of the predefined action. The list of predefined actions
is described in @ref{Implementing VCS actions},

   @item ACTION_LABEL
is the name of the corresponding gps Action that will be launched when
GPS wants to ask the VCS to perform OPERATION,

   @item NAME OF OPERATION
is the name that will appear in the GPS menus when working on a file
under the control of the defined VCS.
@end table

@node Defining revision information
@subsubsection Defining revision information

@noindent
Some VCS reports revisions number from which it is possible to deduce
the related branches. This is the case in CVS for example where a
revision number for a branch uses as prefix the branch point revision
number. For such VCS it is possible to specify two regular
expressions:

@table @b

@item @code{parent_revision}

Parse the revision number and report as first match the parent revision.

@smallexample
  <parent_revision regexp="..." />
@end smallexample

For CVS on @b{1.2.4.5} it must match @b{1.2}.

@item @code{branch_root_revision}

Parse the revision number and report as first match the branch root
revision.

@smallexample
  <branch_root_revision regexp="..." />
@end smallexample

For CVS on @b{1.2.4.5} it must match @b{1.2.4}.
@end table

@node Defining status
@subsubsection Defining status

@noindent
All VCS have the notion of ``status'' or ``state'' to describe the
relationship between the local file and the repository. The XML node
@code{status} is used to describe the status that are known to a
custom VCS, and the icons associated to it:

@smallexample
  <status label="STATUS_LABEL" stock="STOCK_LABEL" />
@end smallexample

Where:
@table @samp
   @item STATUS_LABEL
is the name of the status, for example ``Up to date'' or ``Needs update''
in the context of CVS.
   @item STOCK_LABEL
is the stock identifier of the icon associated to this status, that
will be used, for example, in the VCS Explorer. See section
@ref{Adding stock icons} for more details on how to define stock
icons.
@end table

Note that the order in which status are defined in the XML file is
important: the first status to be displayed must correspond to the
status ``Up-to-date'' or equivalent.

@node Output parsers
@subsubsection Output parsers

@noindent
There are cases in which GPS needs to parse the output of the VCS
commands: when querying the status, or when ``annotating'' a
file.

The following parsers can be implemented in the @code{vcs} node.

@table @b
   @item @code{<status_parser>}, @code{<local_status_parser>} and @code{<update_parser>}
These parsers are used by the command VCS.status_parse, to parse a string for
the status of files controlled by a VCS.

They accept the following child nodes:

@table @b
  @item @code{<regexp>} (mandatory)
Indicates the regular expression to match.
  @item @code{<file_index>}
An index of a parenthesized expression in @code{regexp} that contains the name
of a file.
  @item @code{<status_index>}
An index of a parenthesized expression in @code{regexp} that contains the file
status. This status is passed through the regular expressions defined in the
@code{status_matcher} nodes, see below.
  @item @code{<local_revision_index>}
An index of a parenthesized expression in @code{regexp} that contains the name
of the local revision (the version of the file that was checked out).
  @item @code{<repository_revision_index>}
An index of a parenthesized expression in @code{regexp} that contains the name
of the repository revision (the latest version of the file in the VCS).

  @item @code{<status_matcher>}
A regular expression which, when matching an expressions, identifies the status
passed in the node attribute @code{label}.
@end table

  @item @code{<annotations_parser>}
This parser is used by the command VCS.annotations_parse, to parse a string for
annotations in a file controlled by a VCS.

It accepts the following child nodes:

@table @b
  @item @code{<regexp>} (mandatory)
Indicates the regular expression to match.

  @item @code{<repository_revision_index>} (mandatory)
An index of a parenthesized expression in @code{regexp} that contains the
repository revision of the line.

  @item @code{<author_index>}
An index of a parenthesized expression in @code{regexp} that contains the
author of the line.

  @item @code{<date_index>}
An index of a parenthesized expression in @code{regexp} that contains the
date of the line.

  @item @code{<file_index>}
An index of a parenthesized expression in @code{regexp} that indicates the
part of the line that belongs to the file.

  @item @code{<tooltip_pattern>}
A template pattern that will be used to format the tooltip information.
It can contain text and reference parenthesized expressions in
@code{regexp} using \@code{n} (where @code{n} represents the nth
expression in @code{regexp}).

@end table

  @item @code{<log_parser>}
This parser is used by the command VCS.log_parse, to parse a string for
revision histories in a file controlled by a VCS.

It accepts the following child nodes:

@table @b
  @item @code{<regexp>} (mandatory)
Indicates the regular expression to match.

  @item @code{<repository_revision_index>} (mandatory)
An index of a parenthesized expression in @code{regexp} that contains the
repository revision of the log.

  @item @code{<author_index>}
An index of a parenthesized expression in @code{regexp} that contains the
author of the log.

  @item @code{<date_index>}
An index of a parenthesized expression in @code{regexp} that contains the
date of the log.

  @item @code{<log_index>}
An index of a parenthesized expression in @code{regexp} that contains the
actual text of the log.
@end table

  @item @code{<revision_parser>}
This parser is used by the command VCS.revision_parse, to parse a string for
revision tags and branches in a file controlled by a VCS.

It accepts the following child nodes:

@table @b
  @item @code{<regexp>} (mandatory)
Indicates the regular expression to match.

  @item @code{<sym_index>} (mandatory)
An index of a parenthesized expression in @code{regexp} that contains the
tags or branches symbolic name of the revision.

  @item @code{<repository_revision_index>} (mandatory)
An index of a parenthesized expression in @code{regexp} that contains the
repository revision number of the revision.

@end table

@end table

@node Implementing VCS actions
@subsection Implementing VCS actions

@noindent
A number of ``standard'' VCS operations are known to GPS. Each of
these operations can be implemented, using Actions. See @ref{Defining
Actions}) for a complete description of how to implement actions.

Here is a list of all the defined VCS operations, and their
parameters:

@table @code

@item status_files
  @table @code
     @item $1  = whether the log files should be cleared when obtaining up-to-date status
     @item $2- = the list of files to query status for.
  @end table
  Query the status for a list of files. This should perform a complete
  VCS query and return results as complete as possible.

@item status_dir
  @table @code
    @item $1 = the directory.
  @end table
  Same as above, but works on all the files in one directory.

@item status_dir_recursive
  @table @code
    @item $1 = the directory.
  @end table
  Same as above, but works on all the files in one directory and all
  subdirectories, recursively.

@item local_status_files
  @table @code
    @item $* = list of files
  @end table
  Query the local status for specified files. This query should be as
  fast as possible, not connecting to any remote VCS. The results need
  not be complete, but it is not useful to implement this command if
  the output does not contain at least the working revision.

@item open
  @table @code
    @item $* = list of files
  @end table
  Open files or directories for editing. This command should be
  implemented on any VCS that require an explicit check-out/open/edit
  action before being able to edit a file.

@item update
  @table @code
    @item $* = list of files
  @end table
  Bring the specified files in sync with the latest repository revision.

@item resolved
  @table @code
    @item $* = list of files
  @end table
  Mark files' merge conflics as resolved. Some version control systems
  (like Subversion) will block any commit until this action is called.

@item commit
  @table @code
    @item $1  = log file
    @item $2- = list of files
  @end table
  Commit/submit/check-in files or directories with provided log. The log is
  passed in a file.

@item commit_dir
  @table @code
    @item $1  = log
    @item $2  = directory
  @end table
  Commit/submit one directory with provided log. The log is passed in
  a file.

@item history_text
  @table @code
    @item $1 = file
  @end table
  Query the entire changelog history for the specified file. The result
  is expected to be placed into an editor as plain text.

@item history
  @table @code
    @item $1 = file
  @end table
  Query the entire changelog history for the specified file. The result
  is expected to be placed into a Revision View.

@item history_revision
  @table @code
    @item $1 = revision
    @item $2 = file
  @end table
  Query the history for corresponding revision of the specified file.

@item annotate
  @table @code
    @item $1 = file
  @end table
  Query the annotations for a file.

@item add
  @table @code
    @item $1  = log
    @item $2- = list of files or dirs
  @end table
  Add files/dirs to the repository, with the provided revision log. The
  added files/dirs are commited.

@item add_no_commit
  @table @code
    @item $1  = log
    @item $2- = list of files or dirs
  @end table
  Add files/dirs to the repository, with the provided revision log. The
  added files/dirs are not commited.

@item remove
  @table @code
    @item $1 = log
    @item $2 = file or dir
  @end table
  Remove file/dir from the repository, with the provided revision log.

@item remove_no_commit
  @table @code
    @item $1 = log
    @item $2 = file or dir
  @end table
  Remove file/dir from the repository, with the provided revision log.
  The removed files/dirs are not commited.

@item revert
  @table @code
    @item $* = files
  @end table
  Revert the local file to repository revision, cancelling all local
  changes, and close the file for editing if it was open.

@item diff_patch
  @table @code
    @item $1 = file
  @end table
  Create a textual diff for the given file. This command is used to
  build the activity patch file.

@item diff_head
  @table @code
    @item $1 = file
  @end table
  Display a visual comparison between the local file and the latest
  repository revision. The diff command must report a @i{normal} diff
  as opposed to @i{context} or @i{unified} ones.

@item diff_base_head
  @table @code
    @item $1 = file
  @end table
  Display a visual comparison between the revision from which the file
  has been checked-out and the latest revision. The diff command must
  report a @i{normal} diff as opposed to @i{context} or @i{unified} ones.

@item diff_working
  @table @code
    @item $1 = file
  @end table
  Display a visual comparison between the local file and the revision
  from which it was obtained. The diff command must report a @i{normal} diff
  as opposed to @i{context} or @i{unified} ones.

@item diff
  @table @code
    @item $1 = rev
    @item $2 = file
  @end table
  Display a visual comparison between the local file and the specified
  revision. The diff command must report a @i{normal} diff
  as opposed to @i{context} or @i{unified} ones.

@item diff2
  @table @code
    @item $1 = revision 1
    @item $2 = revision 2
    @item $3 = file
  @end table
  Display a visual comparison between the two specified revisions of
  the file. The diff command must report a @i{normal} diff
  as opposed to @i{context} or @i{unified} ones.

@end table

@c --------------------------------------------------------------------
@node The Server Mode
@section The Server Mode
@cindex server
@c --------------------------------------------------------------------

@noindent
In order to give access to the GPS capabilities from external processes
(e.g. @code{Emacs}), GPS can be launched in @i{server mode}.

The two relevant command line switches are @code{--server} and
@code{--hide}.

@code{--server} will open a socket on the given port, allowing multiple
clients to connect to a running GPS, and sending GPS shell or python
commands.

@code{--hide} tells GPS not to display its main window when starting.
note that under unix systems, you still need to have access to the current
screen (as determined by the @code{DISPLAY} environment variable) in this
mode.

Using the two switches together provides a way to launch GPS as a background
process with no initial user interface.

Clients connecting through a standard socket have access to a simple
shell using @code{GPS>> } as the separating prompt between each command. This
is needed in order to determine when the output (result) of a command
is terminated.

All the GPS shell commands (as defined in @ref{The GPS Shell}) are
available from this shell. In addition, the python interpreter, if
enabled, is also available through the use of the @code{python} prefix
before a python command.

For example, sending @code{pwd} through the socket will send the @code{pwd}
command through the GPS shell and display the result on the socket;
similarly, sending @code{python GPS.pwd()} will send the @code{GPS.help()}
command through the python interpreter (see @ref{The Python Interpreter} for
more details).

The socket shell provides also additional commands:

@itemize @bullet
@item logout
This command will inform the GPS server that the connection should now
be closed.

@item id <string>
This command will register the current session with a given string.
This string can then be used within GPS itself (for example via a
.xml or python plug-in) to display extra information to the client via
the socket, using the command GPS.Socket().send.
@end itemize

For example, let suppose that we start gps with the @code{--server=1234}
command: this will bring up GPS as usual.

Now, on a separate terminal, create a simple client by typing the following:

@smallexample
telnet localhost 1234
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
GPS>> id test-1
id set to 'test-1'
GPS>> pwd
c:\working-dir\
GPS>>
@end smallexample

Then in the GPS Python Console:

@smallexample
>>> GPS.Socket ("test-1").send ("hello, it's time to logout\n");
@end smallexample

At this point, the following is received on the client (telnet) side:

@smallexample
GPS>> hello, it's time to logout
@end smallexample

We can then close the client:

@smallexample
logout
Connection closed by foreign host.
@end smallexample

@c --------------------------------------------------------------------
@node Adding project templates
@section Adding project templates
@cindex project templates
@c --------------------------------------------------------------------

@noindent
The Project template wizard lists a selection of templates. The default
set is found automatically by GPS in the @code{share/gps/templates} directory
of your GPS installation.

It is possible to register new directories in which GPS will look for
templates, by using the Shell/Python command
@code{GPS.ProjectTemplate.add_templates_dir}.

To create a new project template, first create a subdirectory in the
@code{share/gps/templates/} directory, or in one of the directories which has
been registered through @code{GPS.ProjectTemplate.add_templates_dir}. Then, in
this directory, create one template description file.

A template description file is a text file with the @code{.gpt} extension,
with the following syntax:

@smallexample
Name: <name>
Category: <category>
Project: <project file>
<optional_hook_line>

<variable_1>: <variable_1_default_value>: <variable_1_description>
<variable_2>: <variable_2_default_value>: <variable_3_description>
<etc>

[Description]
<the description>
@end smallexample

Where the following should be defined:

@itemize @bullet
@item <name>
The name of the template as it will appear in the template tree in the project
template wizard.

@item <category>
The category in which the template will be inserted in the template tree. There
can be multiple levels of categories, separated with @code{/}.

@item <variable_1>
A name which will be substituted in the template files when deploying the
template, see below.

@item <variable_1_default_value>
The default value for variable 1, which will appear in the project template
wizard.

@item <variable_1_description>
The description of variable 1.

@item <optional_hook_line>
An optional line of the form @code{post_hook: <python_file>} where
@code{<python_file>} is the name of a Python file present in the same directory
as the template description file. This Python file will be run by GPS once,
right after the project template is deployed

@item <description>
A short paragraph describing the project template. This paragraph will be
displayed in the project template wizard when the template is selected in the
tree.

@end itemize

When deploying templates, GPS will copy in the destination directory chosen
by the use all files and directories present in the directory that contains
the template description file, except the Python file indicated as post_hook,
and the template description file itself.

As it deploys templates, GPS will replace strings of the form
@code{@@_<variable_name>_@@} with the value of the variable.
If @code{<variable_name>} is all lower case, the substitution will be
transformed to lower-case. If @code{<variable_name>} is in Mixed_Case, the
substitution will be transformed into Mixed_Case as well. If it is in upper
case, then the substitution will contain the original value specified by the
user.

@c --------------------------------------------------------------------
@node Environment
@chapter Environment
@cindex environment
@c --------------------------------------------------------------------

@menu
* Command Line Options::
* Environment Variables::
* Running GPS on Mac OS X::
* 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] [[+line] source1] [[+line] 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
   --hide              Hide GPS main window
   --host=tools_host   Use tools_host to launch tools (e.g. gdb)
   --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
   --readonly          Open all files in read-only mode
   --server=port       Start GPS in server mode, opening a socket on the
                       given port
   --tracelist         Output the current configuration for logs
   --traceon=name      Activate the logs for a given module
   --traceoff=name     Deactivate the logs for a given module
   --tracefile=file    Parse an alternate configuration file for the logs

Source files can be absolute or relative pathnames.
If you prepend a file name with '=', this file will be
searched anywhere on the project's source path

To open a file at a given line, use the '+line' prefix, e.g.
gps +40 source.adb

@code{tools_host} corresponds to a remote host's nickname as defined in
@ref{Setup the remote servers}.

@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. @xref{Adding New Help Files}.

   @item GPS_CUSTOM_PATH
@cindex GPS_CUSTOM_PATH
Contains a list of directories to search for custom files. See
@ref{Customizing through XML and Python files} for more details.

   @item GPS_CHANGELOG_USER
@cindex GPS_CHANGELOG_USER
Contains the user and e-mail to use in the global ChangeLog
files. Note that the common usage is to have two spaces between the
name and the e-mail. Ex: "John Does  <john.doe@@home.com>"

   @item GPS_STARTUP_PATH
@cindex GPS_STARTUP_PATH
Contains the value of the @code{PATH} environment variable just before GPS
was started. This is used by GPS to restore the proper environment before
spawning applications, no matter what particular directories it needed to
set for its own purpose.

   @item GPS_STARTUP_LD_LIBRARY_PATH
@cindex GPS_STARTUP_LD_LIBRARY_PATH
Same as @code{GPS_STARTUP_LD_LIBRARY_PATH} but for the @code{LD_LIBRARY_PATH}
variable.

   @item GPS_MEMORY_MONITOR
@cindex GPS_MEMORY_MONITOR
If set, GPS will add special code on every allocation and deallocation,
thus slowing things down a bit, that makes it possible to check where the
biggest amount of memory is allocated, through the
@code{GPS.debug_memory_usage} python command.

@end table

@c --------------------------------------------------------------------
@node Running GPS on Mac OS X
@section Running GPS on Mac OS X
@cindex Mac OS
@c --------------------------------------------------------------------

@noindent
The current version of GPS on Mac OS X requires an X11 server. Such a server
is distributed with Mac OS X Panther and Mac OS X Tiger.

Additionally, if you are launching GPS from a standard Terminal, you need to
specify the display on which to launch GPS, by typing:

@code{export DISPLAY=:0}

before launching GPS.

Note: GPS does not support files with line endings in CR.

@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 or
USERPROFILE environment variables are not defined.

   @item $HOME/.gps/log
@cindex log
@anchor{log file}
Log file created automatically by GPS.
When GPS is running, it will create a file named @file{log.<pid>}, where
@file{<pid>} is the GPS process id, so that multiple GPS sessions do not
clobber each other's log. In case of a successful session, this
file is renamed @file{log} when exiting; in case of an unexpected exit
(a bug box will be displayed), the log file is kept under its original name.

Note that the name of the log file is configured by the @file{traces.cfg}
file.

   @item $HOME/.gps/aliases
@cindex aliases
File containing the user-defined aliases (@pxref{Defining text aliases}).

   @item $HOME/.gps/plug-ins
Directory containing files with user-defined plug-ins.
All xml and python 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 through XML and Python files} and
@pxref{Adding support for new languages}.

   @item $HOME/.gps/keys.xml
Contains all the key bindings for the actions defined in GPS or in the
custom files. This only contains the key bindings overridden through the
key shortcuts editor (see @ref{The Key Manager Dialog}).

   @item $HOME/.gps/gtkrc
@cindex Dynamic Key Binding
@cindex gtkrc
Configuration and theme file for gtkrc. This file can be edited to activate
gtk+ specific aspects, or change the look of GPS in some measure. Mostly,
everything can be done through the standard GPS preferences, but this file
can be used to get access to the old GPS preference "Dynamic Key Binding".
This preference activated a gtk+ behavior were key shortcuts for menu can be
changed by simply pressing the appropriate key combination when the mouse is
over that menu. It has various dangereous aspects and is not fully supported
by GPS, so was removed as a preference, but you can add the following line
in @file{gtkrc} to get this back:
@smallexample
gtk-can-change-accels=1
@end smallexample

   @item $HOME/.gps/actions.xml
Contains the definition of all the actions that were defined through the
graphical interface. This is loaded last, and overrides all actions defined
elsewhere.

   @item $HOME/.gps/perspectives.xml
Desktop file in XML format (using the menu @code{File->Save More->Desktop}),
loaded automatically if found.

   @item $HOME/.gps/locations.xml
This file contains the list of locations that GPS has previously edited. It
corresponds to the history navigation (@code{Navigate->Back} and
@code{Navigate->Forward})

   @item $HOME/.gps/properties.xml
This file is used to store file-specific properties across GPS sessions. In
particular, it contains the encoding to use for various files when the
default encoding isn't appropriate.

   @item $HOME/.gps/histories.xml
@cindex history
Contains the state and history of combo boxes (e.g. the
@code{Run->Custom...} dialog).

   @item $HOME/.gps/targets.xml
@cindex targets
Contains the build targets defined by the user.

   @item $HOME/.gps/preferences
@cindex preferences
Contains all the preferences in XML format, as specified in the
preferences menu.

   @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.<pid>}.

This file is created automatically when the @file{$HOME/.gps/} directory is
created. If you remove it manually, it won't be recreated the next time you
start GPS.

   @item $HOME/.gps/startup.xml
This file contains the list of scripts to load at startup, as well as
additional code that need to be executed to setup the script.

   @item $HOME/.gpe/activity_log.tmplt
Template file used to generate activities' group commit-log and patch
file's header. If not present the system wide template (see below) is
used. The set of configurable tags are described into this template.
@cindex activity log template
@cindex activity, log template

   @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}/lib
This directory contains the shared libraries used by GPS.

   @item @i{prefix}/share/doc/gps/html
GPS will look for all the documentation files under this directory.

   @item @i{prefix}/share/examples/gps
This directory contains source code examples.

   @item @i{prefix}/share/examples/gps/language
This directory contains sources showing how to provide a shared library to
dynamically define a new language. See @ref{Adding support for new languages}.

   @item @i{prefix}/share/examples/gps/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/plug-ins
Directory containing files with system-wide plug-ins (xml and python files)
loaded automatically at start-up.

   @item @i{prefix}/share/gps/library
Directory containing files with system-wide plug-ins (xml and python files)
that are not loaded automatically at startup, but can be selected in the
Plug-ins editor.

   @item @i{prefix}/share/gps/gps-animation.png
@cindex png
Default image displayed in the top right corner of GPS when GPS is idle.

   @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. If you remove this file, the idle
image (@file{gps-animation.png}) will always be displayed.

   @item @i{prefix}/share/gps/gps-splash.png
@cindex png
Splash screen displayed by default when GPS is started.

   @item @i{prefix}/share/gps/perspectives.xml
@cindex default desktop
@cindex desktop, default
This is the description of the default desktop that GPS uses when the user
hasn't defined his own default desktop and no project specific desktop exists.
You can modify this file if you want, knowing that this will impact all users
of GPS sharing this installation.
The format of this file is the same as $HOME/.gps/perspectives.xml, which can be
copied from your own directory if you wish.

   @item @i{prefix}/share/gps/default.gpr
@cindex default project
Default project used by GPS. Can be modified after installation time to
provide useful default for a given system or project.

   @item @i{prefix}/share/gps/readonly.gpr
Project used by GPS as the default project when working in a read-only
directory.

   @item @i{prefix}/share/gps/activity_log.tmplt
Template file used by default to generate activities' group commit-log
and patch file's header. This file can be copied into user home
directory and customized (see above).

   @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} if you are a supported
user, and to @uref{mailto:gps-devel@@lists.act-europe.fr} otherwise.

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} may also
bring some useful information when reporting a bug.

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

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

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

There are several solutions to handle this issue:

@itemize @bullet
@item Put all duplicate files in the same project

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

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

@item Use scenario variables in the project

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

@item Use extending projects

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

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

@end itemize

@item GPS is very slow compared to previous versions under unix (GPS < 4.0.0)

GPS versions 4.x need the X RENDER extension when running under unix
systems to perform at a reasonable speed, so you need to make sure your X
server properly supports this extension.

@item Using the space key brings the smart completion window under Ubuntu

This is specific to the way GNOME is configured on Ubuntu distributions.
To address this incompatibility, close GPS, then go to the GNOME menu
@i{System->Preferences->Keyboard} (or launch
@command{gnome-keyboard-properties}).

Select the @i{Layout} tab, click on @i{Layout Options}. Then click twice
on @i{Using space key to input non-breakable space character} and then
select @i{Usual space at any level} and then close the dialogs.

@end table

@c **********************************
@c * GNU Free Documentation License *
@c **********************************
@include gfdl.texi
@c GNU Free Documentation License

@c -------------------------------------------------------------------
@node Index table
@unnumbered Index
@printindex cp

@bye
