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


File: gps.info,  Node: Using an External Editor,  Next: Using the Clipboard,  Prev: Menu Items,  Up: Editing Files

Using an External Editor
========================

GPS is fully integrated with a number of external editors, in
particular `Emacs' and `vi'. The choice of the default external editor
is done in the preferences. *Note The Preferences Dialog::.  The
following values are recognized:

`gnuclient'
     This is the recommended client. It is based on Emacs, but needs an
     extra package to be installed. This is the only client that
     provides a full integration in GPS, since any extended lisp
     command can be sent to the Emacs server.

     By default, gnuclient will open a new Emacs frame for every file
     that is opened. You might want to add the following code to your
     `.emacs' file (create one if needed) so that the same Emacs frame
     is reused every time:

             (setq gnuserv-frame (car (frame-list)))

     See <http://www.hpl.hp.co.uk/people/ange/gnuserv/> for more
     information.

`emacsclient'
     This is a program that is always available if you have installed
     Emacs. As opposed to starting a new Emacs every time, it will
     reuse an existing Emacs session. It is then extremely fast to open
     a file.

`emacs'
     This client will start a new Emacs session every time a file needs
     to be opened. You should use `emacsclient' instead, since it is
     much faster, and makes it easier to copy and paste between multiple
     files. Basically, the only reason to use this external editor is if
     your system doesn't support `emacsclient'.

`vim'
     `Vim' is a vi-like editor that provides a number of enhancements,
     for instance syntax highlighting for all the languages supported by
     GPS. Selecting this external editor will start an xterm (or command
     window, depending on your system) with a running vim process
     editing the file.

     Note that one limitation of this editor is that if GPS needs to
     open the same file a second time, it will open a new editor,
     instead of reusing the existing one.

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

`vi'
     This editor works exactly like vim, but uses the standard `vi'
     command instead of `vim'.

`custom'
     You can specify any external editor by choosing this item. The full
     command line used to call the editor can be specified in the
     preferences (see *Note custom editor command::).

`none'
     No external editor is used, and the contextual menus simply won't
     appear.

   In the cases that require an Emacs server, GPS will try several
solutions if no already running server was found. It will first try to
spawn the glide environment distributed with GNAT. If not found in the
PATH, it will then start a standard Emacs. The project file currently
used in GPS will be set appropriately the first time Emacs is spawned.
This means that if you load a new project in GPS, or modify the paths
of the current project, you should kill any running Emacs, so that a
new one is spawned by GPS with the appropriate project.

   Alternatively, you can reload explicitly the project from Emacs
itself by using the menu `Project->Load'

   In the preferences, there are three settings that allow you to select
the external editor (if left to an empty string, GPS will automatically
select the first editor available on your system), to specify the
custom editor command, in case you've selector this item, and whether
this editor should always be used every time you double-click on a
file, or whether you need to explicitly select the contextual menu to
open the external editor.


File: gps.info,  Node: Using the Clipboard,  Prev: Using an External Editor,  Up: Editing Files

Using the Clipboard
===================

This section concerns X-Window users who are used to cutting and
pasting with the middle mouse button. In the GPS text editor, as in
many recent X applications, the GPS clipboard is set by explicit
cut/copy/paste actions, either through menu items or keyboard
shortcuts, and the primary clipboard (i.e. the "middle button"
clipboard) is set by the current selection.

   Therefore, copy/paste between GPS and other X applications using the
primary clipboard will still work, provided that there is some text
currently selected. The GPS clipboard, when set, will override the
primary clipboard.

   See <http://www.freedesktop.org/standards/clipboards.txt> for more
information.


File: gps.info,  Node: Source Navigation,  Next: Project Handling,  Prev: Editing Files,  Up: Top

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

* Menu:

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


File: gps.info,  Node: Support for Cross References,  Next: The Navigate Menu,  Up: Source Navigation

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

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

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

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

     There are a few special cases where GPS can not find the external
     file (called `ALI file') that contains the cross-reference
     information. Most likely, this is either because you haven't
     compiled your sources yet, or because the source code has changed
     since the `ALI file' was generated.

     It could also be that you haven't included in the project the
     object directories that contain the `ALI files'.

     In addition, one special case can not be handled automatically.
     This is for separate units, whose file names have been crunched
     through the `gnatkr' command. To handle this, you should force GPS
     to parse all the `ALI files' in the appropriate object directory.
     This is done by right-clicking on the object directory in the
     explorer (left-side panel on the main window), and selecting the
     menu "Parse all xref information".

C/C++
     To enable the navigation features for C and C++ source files, you
     need to first generate a database of symbol references, by going
     through the menu Build->Recompute C/C++ Xref info. Messages in the
     console window will indicate the state of the processing. Due to
     the nature of these languages, in order to provide accurate cross
     references, GPS needs to generate the database in two phases: a
     first pass parses all the files that have been modified since the
     previous parsing, and a second pass generates global cross
     references by analyzing the complete database.  It is thus
     expected that for large projects, this phase can take a
     significant amount of CPU to proceed.

     In some cases, GPS won't be able to determine the exact function
     involved in a cross reference. This will typically occur for
     overloaded functions, or if multiple functions with the same name,
     but under different `#ifdef' sections, are defined. In this case,
     GPS will display a dialog listing the possible choices to resolve
     the ambiguity.

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


File: gps.info,  Node: The Navigate Menu,  Next: Source Navigation Contextual Menus,  Prev: Support for Cross References,  Up: Source Navigation

The Navigate Menu
=================

Find/Replace...
     Open the find and replace dialog. *Note Searching and Replacing::.

Find Next
     Find next occurrence of the current search. *Note Searching and
     Replacing::.

Find Previous
     Find previous occurrence of the current search.  *Note Searching
     and Replacing::.

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

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

Goto Line...
     Open a dialog where you can type a line number,  in order to jump
     to a specific location in the current source editor.

Goto File Spec<->Body
     Open the corresponding spec file if the current edited file is a
     body file, or body file otherwise. This option is only available
     for the Ada language.  This item is also accessible through the
     editor's contextual menu

Find All References
     Find all the references to the current entity in the project. The
     search is based on the semantic information extracted from the
     sources, this is not a simple text search. The result of the
     search is displayed in the location window, see *Note The
     Locations Tree::.

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

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

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


File: gps.info,  Node: Source Navigation Contextual Menus,  Prev: The Navigate Menu,  Up: Source Navigation

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

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

Goto declaration of entity
     Go to the declaration/spec of entity. The current entity is
     determined by the word located around the cursor or by the current
     selection if any.  This capability requires support for cross
     references.

Goto body of entity
     Go to the body/implementation of entity.  This capability requires
     support for cross references.

Goto file spec/body
     Open the corresponding spec file if the current edited file is a
     body file, or body file otherwise. This option is only available
     for the Ada language.

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

    `Entity calls'
          Open or raise the call graph browser on the specified entity
          and display all the functions called by entity. *Note Call
          Graph::.

    `Entity is called by'
          Open or raise the call graph browser on the specified entity
          and display all the functions calling entity. *Note Call
          Graph::.

          Note that this capability requires a global look up in the
          project cross references, which may take a significant amount
          of time the first time.  After a global look up, information
          is cached in memory, so that further global queries will be
          faster.

    `Find all references to entity'
          *Note Find All References::.

    `Find all local references to entity'
          Find all references to entity in the current file (or in the
          current top level unit for Ada sources).  See *Note Find All
          References:: for more details.

    `Find all writes to entity'
          Find all writes to an entity. This is a search global to the
          project.  See *Note Find All References:: for more details.

    `Find all reads of entity'
          Find all non write accesses to an entity. This is a search
          global to the project.  See *Note Find All References:: for
          more details.


File: gps.info,  Node: Project Handling,  Next: Searching and Replacing,  Prev: Source Navigation,  Up: Top

Project Handling
****************

The section on the project explorer (*Note The Project Explorer::) has
already given a brief overview of what the projects are, and the
information they contain.

   This chapter provides more in-depth information, and describes how
such projects can be created and maintained.

* Menu:

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


File: gps.info,  Node: Description of the Projects,  Next: Scenarios and Configuration Variables,  Up: Project Handling

Description of the Projects
===========================

Project files and GNAT tools
----------------------------

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

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

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

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

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

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

   If you are using programming languages other than Ada, the project
files can automatically generate Makefiles through the `gpr2make' tool
provided with GNAT. Round trip editing is not available though, and any
change you make to the generated Makefiles will be lost the next time
the tool is run.

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

   * absolute paths

   * relative paths These paths, when used in a with line as described
     below, are relative to the location of the project that does the
     with.

   * ADA_PROJECT_PATH If this environment variable is set, it contains
     a colon-separated (or semicolon under Windows) list of directories
     in which the project files are searched.

Contents of project files
-------------------------

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

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

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

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

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

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

   * List of source directories:    All the sources managed by a
     project are found in one or more    source directories. Each
     project can have multiple source    directories, and a given
     source directory might be shared by    multiple projects.

   * Object directory:    When the sources of the project are compiled,
     the resulting object    files are put into this object directory.
     There exist exactly one object    directory for each project. If
     you need to split the object files    among multiple object
     directories, you need to create multiple    projects importing one
     another as appropriate.

     When sources from imported sub projects are recompiled, the
     resulting object files are put in the sub project's own object
     directory, and will never pollute the parent's object directory.

   * Exec directory:    When a set of object files is linked into an
     executable, this executable    is put in the exec directory of the
     project file. If this attribute    is unspecified, the object
     directory is used.

   * List of source files:    The project is responsible for managing a
     set of source    files. These files can be written in any
     programming    languages. Currently, the graphical interface
     supports Ada, C and C++.

     The default to find this set of source files is to take all the
     files in the source directories that follow the naming scheme (see
       below) for each language. In addition if you edit the
     project file manually, it is possible to provide an explicit list
     of source    files.

     This attribute cannot be modified graphically yet.

   * List of main units:    The main units of a project (or main files
     in some languages) are    the units that contain the main
     subprogram of the application, and    that can be used to link the
     rest of the application.

     The name of the file is generally related to the name of the
     executable.

     A given project file hierarchy can be used to compile and link
     several executables. GPS will automatically update the Compile, Run
       and Debug menu with the list of executables, based on this list.

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

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

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

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

   * Tools:    The project files provide a simple way to change the
     compiler that    should be used to compile the source files, as
     well as the    underlying debugger to use.

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



File: gps.info,  Node: Scenarios and Configuration Variables,  Next: The Project Explorer (Editing Projects),  Prev: Description of the Projects,  Up: Project Handling

Scenarios and Configuration Variables
=====================================

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

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

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

Creating new configuration variables
------------------------------------

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

   There are two main areas in this dialog: in the top line, you specify
the name of the variable. This name is used for two purposes:

   * It is displayed in the project explorer

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


   If you click on the arrow on the right of this name area, GPS will
display the list of all the environment variables that are currently
defined. However, you don't need to pick the name of an existing
variable, neither must the variable exist when GPS is started.

   The second part of this dialog is the list of authorized value for
this variable. Any other value will generate an error reported by GPS,
and the project won't be loaded as a result.

   One of these values is the default value (the one whose button in the
Default column is selected). This means that if the environment
variable doesn't exist when GPS is started, GPS will behave as if it
did exist with this default value.

   The list of possible values can be edited through the `Remove',
`Add' and `Rename' buttons, although you can also simply click on the
value itself to change it.

Editing existing configuration variables
----------------------------------------

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

   This screen shot shows two configuration variables, named `Build'
and `OS', with their current value (resp. `Debug' and `Unix').

   You can easily change the current value of any of these variables by
clicking on the arrow on the right of the value. This will display a
pop-up window with the list of possible values, from which you select
the one you wish to use.

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

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

   You can change the list of possible values for a configuration
variable at any time by clicking on the button to the far left of the
variable's name. This will pop up the same dialog that is used to create
new variables

   Removing a variable is done by clicking on the button immediately to
the left of the variable's name. GPS will then display a confirmation
dialog.

   If you confirm that you want to delete the variable, GPS will simply
remove the variable, and from now on act as if the variable always had
the value it had when it was deleted.


File: gps.info,  Node: The Project Explorer (Editing Projects),  Next: The Project Menu,  Prev: Scenarios and Configuration Variables,  Up: Project Handling

The Project Explorer
====================

The project explorer, as mentioned in the general description of the
GPS window, is one of the two explorers found by default on the left of
the window. It shows in a tree structure the project hierarchy, along
with all the source files belonging to the project, and the entities
declared in the source files.

   It is worth noting that the explorer provides a tree representation
of the project hierarchy. If a project is imported by multiple other
projects in the hierarchy, then this project will appear multiple times
in the explorer.

   Likewise, if you have edited the project manually and have used the
`limited with' construct to have cycles in the project dependencies,
the cycle will expand infinitely. For instance, if project `a' imports
project `b', which in turns imports project `a' through a `limited
with' clause, then expanding the node for `a' will show `b'. In turn,
expanding the node for `b' will show a node for `a', and so on.

   The contextual menu in this explorer provides a number of items to
modify the project hierarchy (what each project imports), as well as to
visualize and modify the attributes for each projects (compilation
switches, naming scheme, ...)

   The following entries are available in the contextual menu:

`Show Projects Imported by...'
     This item will open a new window in GPS, the project browser, which
     displays graphically the relationships between each project in the
     hierarchy.

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

`Edit Project Properties'
     This item will open a new dialog, and give access to all the
     attributes of the project: tool switches, naming schemes, source
     directories, ... *Note The Project Properties Editor::.

`Add Dependency...'
     This menu and its two sub-menus are the primary way to change the
     relationship between projects in the hierarchy. You can either add
     a dependency on an already existing project, or a dependency on a
     newly created project.

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

`Add Configuration Variable'
     This menu item should be used to add new configuration variables,
     as described in *Note Scenarios and Configuration Variables::.

`Edit Project Source File'
     This menu will load the project file into an editor, so that you
     can manually edit it. This should be used if you need to access
     some features of the project files that are not accessible
     graphically (renames statements, variables, ...)

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


File: gps.info,  Node: The Project Menu,  Next: The Project Wizard,  Prev: The Project Explorer (Editing Projects),  Up: Project Handling

The Project Menu
================

   The menu bar item `Project' contains several commands that generally
act on the whole project hierarchy. If you only want to act on a single
project, use the contextual menu in the project explorer.

   Some of these menus apply to the currently selected project. This
notion depends on what window is currently active in GPS: if it is the
project explorer, the selected project is either the selected node (if
it is a project), or its parent project (for a file, directory, ...).
If the currently active window is an editor, the selected project is
the one that contains the file.

   In all cases, if there is no currently selected project, the menu
will apply to the root project of the hierarchy.

   These commands are:

`New'
     This menu will open the project wizard (*Note The Project
     Wizard::), so that you can create new projects. On exit, the
     wizard asks whether the newly project should be loaded. If you
     select `Yes', the newly project will replace the currently loaded
     project hierarchy.

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

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

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

`Save All'
     This will save all the modified projects in the hierarchy.

`Edit File Switches'
     This menu applies to the currently selected project. This will
     open a new window in GPS, listing all the source files for this
     project, along with the switches that will be used to compile
     them, *Note The Switches Editor::.

`Recompute Project'
     Recompute the contents of the project after modifications outside
     of GPS. In particular, it will take into account new files added
     externally to the source directories.  This isn't needed for
     modifications made through GPS. Note also that this doesn't
     re-parse the physical project file on disk. Instead, you can
     reopen the project if you have done manual modifications to it.

`File View and Project View'
     These two menus will open (or raise if they are already open) the
     explorers on the left side of the GPS window.


File: gps.info,  Node: The Project Wizard,  Next: The Project Properties Editor,  Prev: The Project Menu,  Up: Project Handling

The Project Wizard
==================

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

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

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

   The wizard gives access to the following list of pages:

   * Project Naming

   * VCS Selection

   * Source Directories Selection

   * Build Directory

   * Naming Scheme

   * Main Units

   * Switches

Project Naming
--------------

This is the first page displayed by the wizard.

   You must enter the name and location of the project to create. This
name must be a valid Ada identifier (i.e. start with a letter,
optionally followed by a series of digits, letters or underscores).
Spaces are not allowed. Likewise, reserved Ada keywords must be
avoided. If the name is invalid, GPS will display an error message when
you press the `Forward' button.

   In this page, you should also select what languages the source files
in this project are written in. Currently supported are `Ada', `C' and
`C++'. Multiple languages can be used for a single project.

   The last part of this page is used to indicate how the path should be
stored in the generated project file. Most of the time, this setting
will have no impact on your work. However, if you wish to edit the
project files by hand, or be able to duplicate a project hierarchy to
another location on your disk, it might be useful to indicate that
paths should be stored as relative paths (they will be relative to the
location of the project file).

VCS Selection
-------------

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

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

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

   If left blank, no program will be run.

Source Directories Selection
----------------------------

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

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

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

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

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

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

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

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

The object directory is the location where the files resulting from the
compilation of sources (`.o' files for instance) are put.

   One object directory is associated for each project.

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

Naming Scheme
-------------

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

   GPS is very flexible in that respect, and allows you to specify the
default extension for the files in this language. GPS makes a
distinction between spec (or header) files, which generally contains no
executable code, only declarations, and body files which contain the
actual code. For languages other than Ada, this header file is used
rather than the body file when you select `Go To Declaration' in the
contextual menu of editors.

   In a language like Ada, the distinction between spec and body is
part of the definition of the language itself, and you should be sure
to specify the appropriate extensions.

   The default naming scheme for Ada is GNAT's naming scheme (`.ads'
for specs and `.adb' for bodies). In addition, a number of predefined
naming schemes for other compilers are available in the first combo box
on the page. You can also create your own customized scheme by entering
a free text in the text entries.

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

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

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

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

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

   Typically, for C applications, these are the files that contain the
`main()' function. For Ada applications, these are the files that
contain the main subprogram for the partition.

   These files are treated specially by GPS. Some sub-menus of `Build'
and `Debug' will have predefined entries for the main units, which make
it more convenient to compile and link your executables.

   To add main units click on the `Add' button. This opens a file
selection dialog. No check is currently done that the selected file
belongs to the project, but GPS will complain later if it doesn't.

   When compiled, each main unit will generate an executable, whose name
is visible in the second column in this page. If you are using a recent
enough version of GNAT (3.16 or more recent), you can change the name
of this executable by clicking in the second column and changing the
name interactively.

Switches
--------

The last page of the project wizard is used to select the default
switches to be used by the various tools that GPS calls (compiler,
linker, binder, pretty printer, ...).

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

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

Textual selection of switches
     The bottom part is an editable entry field, where you can directly
     type the switches. This makes it easier to move from an older
     setup (e.g. Makefile, script) to GPS, by copy-pasting switches.

   The two parts of the pages are kept synchronized at any time:
clicking on a button will edit the entry field to show the new switch;
adding a new switch by hand in the entry field will activate the
corresponding button if there is one.

   Any switch can be added to the entry field, even if there is no
corresponding button. In this case, GPS will simply forward it to the
tool when it is called, without trying to represent it graphically.


File: gps.info,  Node: The Project Properties Editor,  Next: The Switches Editor,  Prev: The Project Wizard,  Up: Project Handling

The Project Properties Editor
=============================

The project properties editor gives you access at any time to the
properties of your projects. It is accessible through the menu
`Project->Edit Project Properties', and through the contextual menu
`Edit project properties' on any project item, e.g. from the Project
View or the Project Browser.

   If there was an error loading the project (invalid syntax,
non-existing directories, ...), a warning dialog is displayed when you
select the menu. This reminds you that the project might be only
partially loaded, and editing it might result in the loss of data. In
such cases, it is recommended that you edit the project file manually,
which is doable directly from the pop-up dialog.

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

   This editor is divided into three parts:

The attributes editor
     The contents of this editor is very similar to that of the project
     wizard (*note The Project Wizard::). In fact, all pages but the
     `General' page are exactly the same, and you should therefore read
     the description for these in the project wizard chapter.

     The general page gives access to more attributes than the general
     page of the project wizard does. In addition, you can select the
     name of all the external tools that GPS uses (compilers for the
     various languages, linker, pretty-printer, ...).

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

     Clicking on the right title bar (`Project') of this selector will
     sort the projects in ascending or descending order.

     Clicking on the left title bar (untitled) will select or unselect
     all the projects.

     This selector has two different possible presentations, chosen by
     the toggle button on top: you can either get a sorted list of all
     the projects, each one appearing only once. Or you can have the
     same project hierarchy as displayed in the project explorer.

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

     Clicking on the left title bar (untitled, on the left of the
     `Scenario' label) will select all values of all variables.

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


File: gps.info,  Node: The Switches Editor,  Next: The Project Browser,  Prev: The Project Properties Editor,  Up: Project Handling

The Switches Editor
===================

The switches editor, available through the menu `Project->Edit
Switches', lists all the source files associated with the selected
project.

   For each file, the compiler switches are listed. These switches are
displayed in gray if they are the default switches defined at the
project level (*note The Project Properties Editor::). They are defined
in black if they are specific to a given file.

   Double-clicking in the switches column allows you to edit the
switches for a specific file. It is possible to edit the switches for
multiple files at the same by selecting them before displaying the
contextual menu (`Edit switches for all selected files'.

   When you double-click in one of the columns that contain the
switches, a new dialog is opened that allows you to edit the switches
specific to the selected files.

   This dialog has a button titled `Revert'. Clicking on this button
will cancel any file-specific switch, and revert to the default
switches defined at the project level.


File: gps.info,  Node: The Project Browser,  Prev: The Switches Editor,  Up: Project Handling

The Project Browser
===================

The project graph is a special kind of browser (*note Source
Browsing::). It shows the dependencies between all the project in the
project hierarchy. Two items in this browser will be linked if one of
them imports the other.

   It is accessed through the contextual menu in the project explorer,
by selecting the `Show projects imported by...' item, when
right-clicking on a project node.

   Clicking on the left arrow in the title bar of the items will display
all the projects that import that project. Similarly, clicking on the
right arrow will display all the projects that are imported by that
project.

   The contextual menu obtained by right-clicking on a project item
contains several items. Most of them are added by the project editor,
and gives direct access to editing the properties of the project,
adding dependencies...  *Note The Project Explorer (Editing Projects)::.

   Some new items are added to the menu:

`Locate in explorer'
     Selecting this item will switch the focus to the project explorer,
     and highlight the first project node found that matches the
     project in the browser item. This is a convenient way to get
     information like the list of directories or source files for that
     project.

`Show dependencies'
     This item plays the same role as the right arrow in the title bar,
     and display all the projects in the hierarchy that are imported
     directly by the selected project

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

`Show projects depending on'
     This item plays the same role as the left arrow in the title bar,
     and display all the projects that import directly the selected
     project.

