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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


File: gps.info,  Node: The Assembly Window,  Next: The Debugger Console,  Prev: Using the Source Editor when Debugging,  Up: Debugging

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

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

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

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

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

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

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

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

     output /x $eax

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


File: gps.info,  Node: The Debugger Console,  Prev: The Assembly Window,  Up: Debugging

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

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

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

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

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

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

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

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

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

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

          graph display `print /x my_variable`

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

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

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

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

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

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


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

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

* Menu:

* The VCS Explorer::
* The VCS Menu::
* The Version Control Contextual 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 `VCS' tab in the
Project property editor. *Note The Project Properties Editor::.

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

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

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

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


File: gps.info,  Node: The VCS Explorer,  Next: The VCS Menu,  Up: Version Control System

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

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

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

   The VCS Explorer contains the following columns:

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

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

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

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

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

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

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

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

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

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

Working rev.
     Indicates the version of the local file.

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

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

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

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


File: gps.info,  Node: The VCS Menu,  Next: The Version Control Contextual Menu,  Prev: The VCS Explorer,  Up: Version Control System

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Remove annotations
     Remove the annotations from the selected file.

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

Add to repository
     Add a file to the repository.

Remove from repository
     Remove a file from the repository.


File: gps.info,  Node: The Version Control Contextual Menu,  Prev: The VCS Menu,  Up: Version Control System

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

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

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

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

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

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

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

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

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

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

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

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

Remove annotations
     Remove annotations for the selected files.

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

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

Add to repository
     Add the selected items to the repository.

Remove from repository
     Remove the selected items from the repository.

Directory
     Only available when the current context contains directory
     information

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

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

    Update directory
          Update the files in the selected directory.

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

Project
     Only available when the current context contains project
     information

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

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

    Update project
          Updates all the source files in the project.

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

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

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

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

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


File: gps.info,  Node: Tools,  Next: Working in a Cross Environment,  Prev: Version Control System,  Up: Top

Tools
*****

* Menu:

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


File: gps.info,  Node: The Tools Menu,  Next: Visual Comparison,  Up: Tools

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

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

   The list of active items includes:

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

Call Graph
     *Note Call Graph::.

Dependency Browser
     *Note Dependency Browser::.

Entity Browser
     *Note Entity Browser::.

Compare
     *Note Visual Comparison::.


File: gps.info,  Node: Visual Comparison,  Next: Code Fixing,  Prev: The Tools Menu,  Up: Tools

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

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

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

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

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

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

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

   Colors are used to display the different kinds of chunks:

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

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

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

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


File: gps.info,  Node: Code Fixing,  Prev: Visual Comparison,  Up: Tools

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

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

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

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

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

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

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


File: gps.info,  Node: Working in a Cross Environment,  Next: Customizing and Extending GPS,  Prev: Tools,  Up: Top

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

* Menu:

* Customizing your Projects::
* Debugger Issues::

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


File: gps.info,  Node: Customizing your Projects,  Next: Debugger Issues,  Up: Working in a Cross Environment

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

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

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

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

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

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

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

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

Target
     Native, Embedded

Target
     Native, PowerPC, M68K

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

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


File: gps.info,  Node: Debugger Issues,  Prev: Customizing your Projects,  Up: Working in a Cross Environment

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

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

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

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

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

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

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


File: gps.info,  Node: Customizing and Extending GPS,  Next: Environment,  Prev: Working in a Cross Environment,  Up: Top

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

* Menu:

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


File: gps.info,  Node: The Preferences Dialog,  Next: Customizing the Menu and Tool Bar,  Up: Customizing and Extending GPS

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

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

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

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

   * General

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

    General

         Default font
               The default font used in GPS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

         Select Window
               The key shortcut used to switch between windows.

   * Editor
    General

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

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

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

         Tooltips
               Whether tool tips should be displayed automatically.

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

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

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

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

         External editor
               The default external editor to use.

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

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

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

              `%c'
                    column to display

              `%f'
                    full pathname of file to edit

              `%e'
                    extended lisp command

              `%p'
                    top level project file name

              `%%'
                    percent sign ('%')

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

    Fonts & Colors

         Keywords
               Font and colors used to highlight keywords.

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

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

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

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

         Line highlighting color
               Color for highlighting lines.

         Default font
               The font used in the source editor.

    Ada

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

         Use tabulations
               Whether the editor should use tabulations when indenting.

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

         Continuation lines
               The number of extra spaces for continuation lines.

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

                    variable1,
                        variable2,
                        variable3 : Integer;

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

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

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

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

    C/C++

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

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

         Default indentation
               The number of spaces for the default indentation.

    Keys

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

         Completion
               Key used for automatic completion of identifiers.

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

   * Debugger
    General

         Color highlighting
               Color used for highlighting in the debugger console.

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

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

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

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

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

    Assembly

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

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

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

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

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

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

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

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

    Memory

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

         Color highlighting
               Color used for highlighted items.

         Selection
               Color used for selected items.

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

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

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

    Execute command
          Program used to execute commands externally.

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

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

   * Browsers
    General

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

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

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

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

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

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

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

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

    File Dependencies

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

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

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

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

         -b
               Ignore changes in amount of white space.

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

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

         -w
               Ignore white space when comparing lines.

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

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

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

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

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

    File index
          Index of filename in the file pattern.

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

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

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



File: gps.info,  Node: Customizing the Menu and Tool Bar,  Next: Adding Support for New Languages,  Prev: The Preferences Dialog,  Up: Customizing and Extending GPS

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

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

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

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

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

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

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

   Here is an example for such a file:


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

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

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

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

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

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

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

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

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


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

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


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

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

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

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

`Menu_Item'
     A menu item inside a submenu.

`Action'
     External command associated with a menu item.

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

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

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

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

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

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

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


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

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

`Title'
     Name of the custom button.

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

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

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

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

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

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

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

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

`%pp'
     The current project file pathname.

`%PP'
     The root project pathname.

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

    `P'
          the root project.

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

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

    `d'
          list the source directories.

    `s'
          list the source files.

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

   Examples:

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

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

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

