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


File: gps.info,  Node: Adding Support for New Languages,  Next: Defining Text Aliases,  Prev: Customizing the Menu and Tool Bar,  Up: Customizing and Extending GPS

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

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

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

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

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

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

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

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

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

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

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

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

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

    `String_Delimiter'
          A character defining the string delimiter.

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

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

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

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

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

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

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

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

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

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

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


File: gps.info,  Node: Defining Text Aliases,  Next: Defining New Styles and Key Bindings,  Prev: Adding Support for New Languages,  Up: Customizing and Extending GPS

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

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

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

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

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

   The following special entities are currently defined:

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

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

`%D'
     This is the current date, in ISO format. The year is displayed
     first, then the month and the day

`%H'
     This is the current time (hour, minutes and seconds)

`%l'
     If the expansion of the alias is done in a source editor, this is
     the line on which the cursor is when pressing <control-o>.

`%c'
     This is similar to %l, except it returns the current column.

`%f'
     If the expansion is done in a source editor, this is the name of
     the current file (its base name only, this doesn't include the
     directory)

`%d'
     If the expansion is done in a source editor, this is the directory
     in which the current file is

`%p'
     If the expansion is done in a source editor, this is the base name
     of the project file to which the file belongs.

`%P'
     If the expansion is done in a source editor, this is the full path
     name to the project file (directory and base name).

   The indentation as set in the expansion of the alias is preserved
when the alias is expanded. All the lines will be indented the same
amount to the right as the alias name.

   The third part of the aliases editor, at the top right corner, lists
the parameters for the currently selected alias. Any time you insert a
%(name) string in the expansion text, GPS automatically detects there
is a new parameter reference (or an old reference has changed name or
was removed); the list of parameters is automatically updated to show
the current list.

   Each parameters has three attributes:

name
     This is the name you use in the expansion text of the alias in the
     %(name) special entity.

Environment
     This specifies whether the default value of the parameter comes
     from the list of environment variables set before GPS was started.

default value
     Instead of getting the default value from the environment variable,
     you can also specify a fixed text.  Clicking on the initial value
     of the currently selected variable opens a text entry which you
     can use to edit this default value.

   When an alias that contains parameters is expanded, GPS will first
display a dialog to ask for the value of the parameters. You can
interactively enter this value, which replaces all the %(name) entities
in the expansion text.

Aliases files
-------------

GPS manages multiple aliases files. One of them is editable
interactively by the user through the `Edit->Aliases' menu, whereas all
the others are defined system-wide, and are not editable interactively.

   The user-defined file is `$HOME/.gps/aliases'.

   The system files are all the files stored in the directory
`<prefix>/share/gps/aliases', where `<prefix>' is the path in which GPS
was installed. The aliases defined in these files are read-only, and
indicated as such in the aliases editor.

   All the files have the same XML format, which can be seen in the
following example. Each alias has its own <alias> tag.

     <?xml version="1.0"?>
     <Aliases>
       <alias name="proc" >
         <param name="p" >Proc1</param>
         <param environment="true" name="env" />
         <text>procedure %(p) is
     %(env)%_
     end %(p);</text>
       </alias>
     </Aliases>

   The following tags are available:

`alias'
     This indicates the start of a new alias. It has one mandatory
     attribute, `name', which the text to type in the source editor
     before pressing <control-o>.

`param'
     These are children of the `alias' node. There is one per parameter
     of the alias. They have one mandatory attribute, `name', which is
     the name to type between %(name) in the alias expansion text.

     They have one optional attribute, `environment', which indicates
     the default value must be read from the environment variables if
     it is set to true.

     These tags contain text, which is the default value for the
     parameter.

`text'
     This is a child of the `alias' node, whose value is the
     replacement text for the alias.


File: gps.info,  Node: Defining New Styles and Key Bindings,  Next: Scripting GPS,  Prev: Defining Text Aliases,  Up: Customizing and Extending GPS

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

In addition to the preferences dialog, GPS can be configured through the
Gtk+ mechanism of `RC files'. You can create a text file called `gtkrc'
in the gps home directory (`~/.gps' on Unix systems), or as a global
change, in the directory etc/gps in the GPS installation.

   This file follows the Gtk+ resource file syntax and gives the
possibility in particular to define a number of styles and key bindings
and attach them to particular visual objects such as text editors, menu
items, ...

   For example, you can set <Ctrl-v> in the source editors to scroll
forward one page. The following code defines this new key binding:


     # Create new key bindings for text editors
     binding "custom-text-key"
     {
        # define Ctrl-v to scroll forward one page
        bind "<ctrl>v" { "move-cursor" (pages, 1, 0) }
     }
     
     # Associate the new binding created above with text editors
     class "GtkTextView" binding "custom-text-key"

Toplevel declarations
---------------------

An RC file is a text file which is composed of a sequence of
declarations.  All the literals are case sensitive; `#' characters
delimit comments and the portion of a line after a `#' is ignored when
parsing an RC file.  The syntax of the top-level declarations is
described below.  Opening/closing brackets on the same line ({ ... })
are used to represent a sequence of 0 or more elements. Brackets on
their own line are real bracket characters.

     toplevel-declarations ::=
        { declaration }
     
     declaration ::=
        include-file | pixmap-path | style-definition | binding-definition |
        enable-resource
     
     include-file ::=
        include string_literal
     
     pixmap-path ::=
        pixmap_path string_literal
     
     style-definition ::=
        style resource-name [ = parent ]
        {
           sequence-of-style
        }
     
     binding-definition ::=
        binding resource-name
        {
           sequence-of-binding
        }
     
     enable-resource ::=
        class "widget-name" (binding | style) resource-name
     
     resource-name ::=
        string_literal

The table below describes the meaning of each of these toplevel
declarations:

`include filename'
     Parses another file at this point. If filename is not an absolute
     filename, it is searched in the directories of the currently open
     RC file.

`pixmap_path path'
     Sets a path (a list of directories separated by colons) that will
     be searched for pixmaps referenced in RC files.

`style name [ = parent ] { ... }'
     Declares a style. If parent is specified, name inherits its
     default attributes from parent. You can specify "default" to
     designate the default style, e.g:

          style "my-style" = "default" { ... }

     See *Note Defining new styles:: for more details.

`binding name { ... }'
     Declares a binding set.  See *Note Defining new key bindings:: for
     more details.

`class widget-name (binding | style) name'
     Specifies a binding or style set for a particular set of visual
     objects.

`resource-name'
     An arbitrary user defined name.

Defining new styles
-------------------

A RC style is specified by a style declaration in a RC file, and then
bound to visual objects with a class declaration.  Within each type of
declaration, later declarations override earlier ones.

   For example, the following code will change the background color of
any button, when it is pressed. It will also set a background pixmap
when it is not pressed. The style also inherits from the one above, so
that the buttons also use the default font.


     pixmap_path "directory_that_contains_the_pixmap"
     style "custom-button" = "default"
     {
       bg_pixmap[NORMAL]="pixmap_file"
       bg[ACTIVE]="blue"
     }
     class "GtkButton" style "custom-button"

Here is the syntax for defining styles:


     sequence-of-style ::=
        { style | property }
     
     style ::=
        style-name[state] = string_literal
     
     style-name ::=
        bg | fg | base | text | bg_pixmap | font_name
     
     state ::=
        NORMAL | ACTIVE | PRELIGHT | SELECTED | INSENSITIVE
     
     property ::=
        widget-name::widget-property = value
     
     widget-property ::=
        cursor-aspect-ratio | cursor-color

The table below describes the meaning of each of these elements:

`bg[state] = color'
     Sets the color used for the background of most visual objects.

`fg[state] = color'
     Sets the color used for the foreground of most visual objects.

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

`text[state] = color'
     Sets the color used for foreground of visual objects using base
     for the background color.

`bg_pixmap[state] = pixmap'
     Sets a background pixmap to be used in place of the bg color. The
     special value "<parent>" may be used to indicate that the visual
     object should use the same background pixmap as its parent. The
     special value "<none>" may be used to indicate no background
     pixmap.

`font_name = font'
     Sets the font for a visual object.  Font is a font name as listed
     in the font selector in the preferences dialog, e.g. "Sans Italic
     10".

`GtkTextView::cursor-aspect-ratio = value'
     Width ratio with which to draw the insertion cursor. Value is a
     float value between 0.0 and 1.0. The default value is 0.04.

`GtkTextView::cursor-color = color'
     Color with which to draw insertion cursor

The colors and background pixmaps are specified as a function of the
state of the visual object. The states are:

`NORMAL'
     A color used for a visual object in its normal state.

`ACTIVE'
     A variant of the NORMAL color used when the visual object is in
     the active state, and also for the trough of a ScrollBar, tabs of a
     NoteBook other than the current tab and similar areas. Frequently,
     this should be a darker variant of the NORMAL color.

`PRELIGHT'
     A color used for visual objects in the PRELIGHT state. This state
     is used for Buttons and MenuItems that have the mouse cursor over
     them, and for their children.

`SELECTED'
     A color used to highlight data selected by the user. For instance,
     the selected items in a list object, and the selection in an
     editable object.

`INSENSITIVE'
     A color used for the background of visual objects that have been
     set insensitive.

   Colors can be specified as a string containing a color name (under
Unix systems, GTK+ knows all names from the X color database
/usr/lib/X11/rgb.txt), in one of the hexadecimal forms `#rrrrggggbbbb',
`#rrrgggbbb', `#rrggbb', or `#rgb', where r, g and b are hex digits, or
they can be specified as a triplet `{r, g, b}', where r, g and b are
either integers in the range 0-65535 or floats in the range 0.0-1.0.

Defining new key bindings
-------------------------

Key bindings allow you to specify actions to be taken on a given key
press. The syntax to define new key bindings is described below.


     sequence-of-binding ::=
        { binding }
     
     binding ::=
        bind "key-name"
        {
           sequence-of-commands
        }
     
     sequence-of-commands ::=
        { command }
     
     command ::=
        "command-kind" (parameters)
     
     parameters ::=
        [first-parameter {, number}]
     
     widget-name ::=
        GtkButton | GtkDialog | GtkEntry | GtkMenuItem |
        GtkMenuShell | GtkTextView | GtkTreeView
     
     command-kind ::=
        move-cursor | page-horizontally | set-anchor | insert-at-cursor |
        delete-from-cursor | cut-clipboard | copy-clipboard | paste-clipboard |
        toggle-overwrite | move-focus | activate | select-all | unselect-all |
        select-cursor-row | toggle-cursor-row | expand-collapse-cursor-row |
        select-cursor-parent | start-interactive-search | clicked | close |
        move-current
     
     first-parameter ::=
        movement-step | count | extend-selection | delete-type | start-editing |
        logical | expand | expand-all | menu-direction | string_litteral
     
     number ::=
        [-|+]digit{digit}
     
     key-name ::=
        {modifier}key
     
     modifier ::=
        <ctrl> | <alt> | <shift>
     
     key ::=
        letter | digit |
        BackSpace | Tab | Return | Pause | Scroll_Lock | Sys_Req | Escape |
        Delete | Home | Left | Up | Right | Down | Page_Up | Page_Down | End |
        Insert | Break | Num_Lock |
        F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F10 | F11 | F12 |
        Caps_Lock | space | exclam | quotedbl | numbersign | dollar | percent |
        ampersand | apostrophe | quoteright | parenleft | parenright | asterisk |
        plus | comma | minus | period | slash | colon | semicolon | less |
        equal | greater | question | at | bracketleft | backslash |
        bracketright | underscore | grave | quoteleft | braceleft | bar |
        braceright

The list of valid `command-kind' values and their parameters depend on
the widget name:

`GtkButton'
     Applies to buttons.
    `clicked ()'
          Generate a button click event.

`GtkDialog'
     Applies to dialog windows.
    `close ()'
          Close the current dialog box.

`GtkEntry'
     Applies to single line text entries.
    `activate ()'
          Activate the text entry.

    `move-cursor (movement-step, count, extend-selection)'
          Move insertion point by count steps. If extend-selection is
          true,       create or extend the selection.

    `insert-at-cursor (string)'
          Insert a given text string at the cursor.

    `delete-from-cursor (delete-type, count)'
          Delete count units from the cursor.

    `cut-clipboard ()'
          Cut the current selection to the clipboard.

    `copy-clipboard ()'
          Copy the current selection to the clipboard.

    `paste-clipboard ()'
          Paste the contents of the clipboard.

    `toggle-overwrite ()'
          Toggle the current overwrite mode.

`GtkMenuItem'
     Applies to menu items.
    `activate ()'
          Activate the menu item.

`GtkMenuShell'
     Applies to menus.
    `move-current (menu-direction)'
          Move the current menu entry to the given direction.

`GtkTextView'
     Applies to source and text editors.
    `move-cursor (movement-step, count, extend-selection)'
          Move insertion point by count steps. If extend-selection is
          true,       create or extend the selection.

    `page-horizontally (count, extend-selection)'
          Move cursor to the beginning (count=-1) or the end (count=1)
          of the       current line.

    `set-anchor ()'
          Move the anchor to the cursor position.

    `insert-at-cursor (string)'
          Insert a given text string at the cursor.

    `delete-from-cursor (delete-type, count)'
          Delete count units from the cursor.

    `cut-clipboard ()'
          Cut the current selection to the clipboard.

    `copy-clipboard ()'
          Copy the current selection to the clipboard.

    `paste-clipboard ()'
          Paste the contents of the clipboard.

    `toggle-overwrite ()'
          Toggle the current overwrite mode.

`GtkTreeView'
     Applies to tree and list objects, in particular the Location Tree,
     the    Project View, the File View and the VCS Explorer.
    `move-cursor (movement-step, count)'
          Move insertion point.

    `select-all ()'
          Select all rows.

    `unselect-all ()'
          Unselect all rows.

    `select-cursor-row (start-editing)'
          Select or unselect the current row.

    `toggle-cursor-row ()'
          Toggle the selection of the current row.

    `expand-collapse-cursor-row (logical, expand, expand-all)'
          Expand (expand=1) or collapse (expand=0) the current row.
            If expand-all=1, also expand all children recursively.
            Parameter logical currently ignored.

    `select-cursor-parent ()'
          Select the parent row of the current selection.

    `start-interactive-search ()'
          Start interactive search on the tree view. This will open a
          small window       at the bottom of the tree view where you
          can interactively type names.        The first matching name
          in the tree will be selected while you type it.        You
          can then also use the <up> and <down> keys to navigate through
               all the items matching the current text.

The possible values of the parameters listed above are:

`count'
     Signed integer value.

`string'
     Quoted string, e.g "text".

`extend-selection, start-editing, logical, expand, expand-all:'
     Boolean value. 0 means false, 1 means true.

`delete-type'

    `chars'
          Delete a given amount of characters.

    `word-ends'
          Delete only the portion of the word to the left/right of
          cursor if we're       in the middle of a word.

    `paragraph-ends'
          Delete between cursor and the end (count=1) or beginning
          (count=-1) of       current line.

    `paragraphs'
          Delete whole line.

    `whitespace'
          Delete all white spaces around the cursor.

`menu-direction'

    `parent'
          Select the parent menu item.

    `child'
          Select the first child menu item.

    `next'
          Select the next (sibling) menu item.

    `prev'
          Select the previous (sibling) menu item.

`movement-step'

    `logical-positions'
          Move by forward/back graphemes.

    `visual-positions'
          Move by left/right graphemes.

    `words'
          Move by forward/back words.

    `display-lines'
          Move up/down lines (wrapped lines).

    `display-line-ends'
          Move to either end of a line (wrapped lines).

    `paragraphs'
          Move up/down paragraphs (newline-ended lines).

    `paragraph-ends'
          Move to either end of a paragraph.

    `pages'
          Move by pages.

    `buffer-ends'
          Move to the end (count=1) or to the beginning (count=-1) of
          the file.


File: gps.info,  Node: Scripting GPS,  Prev: Defining New Styles and Key Bindings,  Up: Customizing and Extending GPS

Scripting GPS
=============

* Menu:

* Scripts::
* The GPS Shell::


File: gps.info,  Node: Scripts,  Next: The GPS Shell,  Up: Scripting GPS

Scripts
-------

Scripts are small programs that interact with GPS and allow you to
perform complex tasks repetitively and easily. GPS includes support for
two scripting languages currently, although additional languages might
be added in the future. These two languages are described in the
following section.

   Support for scripting is currently work in progress in GPS. As a
result, not many commands are currently exported by GPS, although their
number is increasing daily. These commands are similar to what is
available to people who extend GPS directly in Ada, but with a strong
advantage: they do not require any recompilation of the GPS core, and
can be tested and executed interactively.

   The goal of such scripts is to be able to help automate processes
such as builds, automatic generation of graphs,...

   All the scripting languages share the same set of commands exported
by GPS, thanks to a abstract interface defined in the GPS core. As a
result, GPS modules do not have to be modified when new scripting
languages are added.

   Scripts can be executed immediately upon startup of GPS by using the
command line switch `--load'. Specifying the following command line:

     gps --load=shell:mytest.gps

   will force the gps script `mytest.gps' to be executed immediately,
before GPS starts reacting to user's requests. This is useful if you
want to do some special initializations of the environment. It can also
be used as a command line interface to GPS, if you script's last
command is to exit GPS.

   In line commands can also be given directly on the command line
through `--eval' command line switch.

   For instance, if you want to analyze an entity in the entity browser
from the command line, you would pass the following command switches:

     gps --eval=shell:'Entity entity_name file_name; Entity.show %1'


File: gps.info,  Node: The GPS Shell,  Prev: Scripts,  Up: Scripting GPS

The GPS Shell
-------------

The GPS shell is a very simple-minded, line-oriented language. It is
accessible through the `Shell' window at the bottom of the GPS window.
It is similar to a Unix shell, or a command window on Windows systems.

   Type `help' at the prompt to get the list of available commands, or
`help' followed by the name of a command to get more information on
that specific command.

   The following example shows how to get some information on a source
entity, and find all references to this entity in the application. It
searches for the entity "entity_name", which has at least one reference
anywhere in the file "file_name.adb". After the first command, GPS
returns an identifier for this entity, which can be used for all
commands that need an entity as a parameter, as is the case for the
second command. When run, the second command will automatically display
all matching references in the location window.

     GPS> Entity my_entity file_name.adb
     <Entity_0x09055790>
     GPS> Entity.find_all_refs <Entity_0x09055790>

   Since the GPS shell is very simple, it doesn't provide any reference
counting for the result types. As a result, all the values returned by
a command, such as `<Entity_0x09055790>' in the example above, are kept
in memory.

   The GPS shell provides the command `clear_cache' which removes all
such values from the memory. After this command is run, you can no
longer use references obtained from previous commands, although of
course you can run these commands again to get a new reference.

   The return value of the 9 previous commands can easily be recalled by
passing `%1', `%2',... on the command line. For instance, the previous
example could be rewritten as

     GPS> Entity my_entity file_name.adb
     <Entity_0x09055790>
     GPS> Entity.find_all_refs %1

   These return values will be modified also for internal commands sent
by GPS, so you should really only use this when you emit multiple
commands at the same time, and don't do any other action in GPS. This
is mostly useful when used for command-line scripts (see `--eval' and
`--load'), or for custom files, *Note Customizing the Menu and Tool
Bar::.

   In future versions of GPS, it will be possible to use more advanced
scripting languages such as `Python'.


File: gps.info,  Node: Environment,  Prev: Customizing and Extending GPS,  Up: Top

Environment
***********

* Menu:

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


File: gps.info,  Node: Command Line Options,  Next: Environment Variables,  Up: Environment

Command Line Options
====================

     Usage:
        gps [options] [-Pproject-file] [source1] [source2] ...
     Options:
        --help              Show this help message and exit
        --version           Show the GPS version and exit
        --debug[=program]   Start a debug session and optionally load the
                            program with the given arguments
        --debugger debugger Specify the debugger's command line
        --target=TARG:PRO   Load program on machine TARG using protocol PRO
        --load=lang:file    Execute an external file written in the language lang
        --eval=lang:file    Execute an in-line script written in the language lang
     
     Source files are searched everywhere on the project's source path


File: gps.info,  Node: Environment Variables,  Next: Files,  Prev: Command Line Options,  Up: Environment

Environment Variables
=====================

The following environment variables can be set to override some default
settings in GPS:

`GPS_ROOT'
     Override the default root directory specified when GPS is built
     (during the configure process, see the file `INSTALL' in the GPS
     sources for more details) to access information such as the
     location of the translation files.

`GPS_HOME'
     Override the variable HOME if present. All the configuration files
     and directories used by GPS are either relative to $HOME/.gps
     (%HOME%\.gps under Windows) if GPS_HOME is not set, or to
     $GPS_HOME/.gps (respectively %GPS_HOME%\.gps) if set.

`GPS_DOC_PATH'
     Set the search path for the documentation. See *Note Integrated
     Help:: for more details.


File: gps.info,  Node: Files,  Next: Reporting Suggestions and Bugs,  Prev: Environment Variables,  Up: Environment

Files
=====

`$HOME/.gps'
     GPS state directory. Defaults to C:\.gps under Windows systems if
     HOME is not defined.

`$HOME/.gps/log'
     Log file created automatically by GPS

`$HOME/.gps/aliases'
     File containing the user-defined aliases (*note Defining Text
     Aliases::).

`$HOME/.gps/customize'
     Directory containing files with user-defined customizations.  All
     files found under this directory are loaded by GPS during start up.
     You can create/edit these files to add your own menu/tool-bar
     entries in GPS, or define support for new languages.  *note
     Customizing the Menu and Tool Bar:: and *note Adding Support for
     New Languages::.

`$HOME/.gps/custom_key'
     Contains all the key bindings defined in GPS. This file is
     automatically created if you have activated the dynamic key
     bindings feature (*note Customizing the Menu and Tool Bar::).

`$HOME/.gps/debugger.log'
     Log file created by the integrated debugger to trace of
     communication between GPS and gdb.

`$HOME/.gps/desktop'
     Desktop file in XML format (using the menu
     `File->Save...->Desktop'), loaded automatically if found.

`$HOME/.gps/gtkrc'
     The theme used by the gtk+ library on which gps is based. It
     allows you to configure the colors and fonts used in your
     application. *Note Defining New Styles and Key Bindings::.  See
     also `<prefix>/etc/gps/gtkrc'.

`$HOME/.gps/history'
     Contains the state and history of combo boxes (e.g. the
     `Run->Custom...' dialog).

`$HOME/.gps/preferences'
     Contains all the preferences in XML format, as specified in the
     preferences menu.

`$HOME/.gps/sessions'
     Directory containing the debugging sessions.

`$HOME/.gps/sessions/session'
     Each file in the `sessions' directory represents a particular
     session saved by the user.

`$HOME/.gps/traces.cfg'
     Default configuration for the system traces. These traces are used
     to analyze problems with GPS. By default, they are sent to the
     file `$HOME/.gps/log'.

`prefix'
     The prefix directory where GPS is installed, e.g `/opt/gps'.

`prefix/bin'
     The directory containing the GPS executables.

`prefix/etc/gps'
     The directory containing global configuration files for GPS.

`prefix/etc/gps/gtkrc'
     The global theme used by the gtk+ library. See also
     `$HOME/.gps/gtkrc'.

`prefix/etc/gps/pangorc'
     The pango (generic font handling) configuration file.

`prefix/etc/gps/pangox.aliases'
     File defining font aliases to X font set.

`prefix/lib'
     This directory contains the shared libraries used by GPS.

`prefix/doc/gps/html'
     GPS will look for all the documentation files under this directory.

`prefix/doc/gps/examples'
     This directory contains source code examples.

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

`prefix/share/gps/aliases'
     Directory containing files with system-wide aliases (*note
     Defining Text Aliases::).

`prefix/share/gps/customize'
     Directory containing files with system-wide customizations (*note
     Adding Support for New Languages::).

`prefix/share/gps/gps-animation.gif'
     Animated image displayed in the top right corner of GPS to
     indicate that actions (e.g compilation) are on going.

`prefix/share/gps/gps-splash.jpg'
     Splash screen displayed by default when GPS is started.

`prefix/share/themes'
     Directory containing the Gtk+ predefined themes.

`prefix/share/make'
     Directory containing shared makefiles used by the multi-language
     build system.

`prefix/share/locale'
     Directory used to retrieve the translation files, when relevant.


File: gps.info,  Node: Reporting Suggestions and Bugs,  Next: Solving Problems,  Prev: Files,  Up: Environment

Reporting Suggestions and Bugs
==============================

If you would like to make suggestions about GPS, or if you encountered
a bug, please report it to `mailto:report@gnat.com' following the usual
GNAT reports recommendations as explained in the file README.GNATPRO
for supported users, and in gnatinfo.txt for non supported users.

   Please try to include a detailed description of the problem,
including sources to reproduce it if possible/needed, and/or a scenario
describing the actions performed to reproduce the problem, as well as
the tools (e.g debugger, compiler, call graph) involved.

   The files `$HOME/.gps/log' and `$HOME/.gps/debugger.log' may also
bring some useful information when reporting a bug.

