16. Environment
16.1 Command Line Options
| Usage:
gps [options] [-P project-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 can be absolute or relative pathnames.
If you prepend a file name with '=', this file will be
searched anywhere on the project's source path
|
16.2 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 3. Integrated Help for
more details.
- `GPS_CUSTOM_PATH'
-
Contains a list of directories to search for custom files. See
15.3 Customizing the Menu and Tool Bar for more details.
16.3 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.
When GPS is running, it will create a file named `log.<pid>', where
`<pid>' is the GPS process id, so that multiple GPS sessions do not
clobber each other's log. In case of a successful session, this
file is renamed `log' when exiting; in case of an unexpected exit
(a bug box will be displayed), the log file is kept under its original name.
Note that the name of the log file is configured by the `traces.cfg'
file.
- `$HOME/.gps/aliases'
-
File containing the user-defined aliases (see section 15.5 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.
see section 15.3 Customizing the Menu and Tool Bar and
see section 15.4 Adding Support for New Languages.
- `$HOME/.gps/custom_key'
- Contains all the menu shortcuts defined in GPS. This file is
automatically created if you have activated the dynamic key bindings feature
(see section 15.3 Customizing the Menu and Tool Bar).
- `$HOME/.gps/keys.xml'
- Contains all the key bindings for the actions defined in GPS or in the
custom files. This only contains the key bindings overridden through the
key shortcuts editor (see 15.2 The Key Manager Dialog).
- `$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 More->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. See section 15.7 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.<pid>'.
This file is created automatically when it does not exist. When
upgrading to a new version of GPS, it is recommended to remove it since
its contents may change from version to version.
- `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/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/language'
- This directory contains sources showing how to provide a shared library to
dynamically define a new language. See 15.4 Adding Support for New Languages.
- `prefix/doc/gps/examples/tutorial'
- This directory contains the sources used by the GPS tutorial.
See gps-tutorial.html.
- `prefix/share/gps/customize'
- Directory containing files with system-wide customizations
(see 15.4 Adding Support for New Languages and
15.5 Defining Text Aliases).
- `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.
16.4 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.
In case GPS generates a bug box, the log file will be kept under a separate
name (`$HOME/.gps/log.<pid>' so that it does not get erased by further
sessions. Be sure to include the right log file when reporting a bug box.
16.5 Solving Problems
This section addresses some common problems that may arise when using or
installing GPS.
- `Non-privileged users cannot start GPS'
- Q: I have installed GPS originally as super user, and ran GPS successfully,
but normal users can't.
A: You should check the permissions of the directory $HOME/.gps and its
subdirectories, they should be owned by the user.
- `GPS crashes whenever I open a source editor'
- This is usually due to font problems. Editing the file
`$HOME/.gps/preferences' and changing the name of the fonts, e.g
changing Courier by Courier Medium, and Helvetica by Sans
should solve the problem.
- `GPS refuses to start the debugger'
-
If GPS cannot properly initialize the debugger (using the menu
Debug->Initialize
), it is usually because the underlying debugger
(gdb) cannot be launched properly. To verify this, try to launch the
'gdb' command from a shell (i.e outside GPS). If gdb cannot be launched from
a shell, it usually means that you are using a wrong version of gdb
(e.g a version of gdb built for Solaris 8, but run on Solaris 2.6).
- `GPS is frozen during a debugging session'
-
If GPS is no longer responding while debugging an application you should
first wait a little bit, since some communications between GPS and gdb
can take a long time to finish. If GPS is still not responding after a
few minutes, you can usually get the control back in GPS by either typing
Ctrl-C in the shell where you've started GPS: this should unblock it;
if it does not work, you can kill the gdb process launched by GPS using the
ps
and kill
, or the top
command under Unix,
and the Task Manager
under Windows: this will terminate your debugging
session, and will unblock GPS.
- `My Ada program fails during elaboration. How can I debug it ?'
-
If your program was compiled with GNAT, the main program is
generated by the binder. This program is an ordinary Ada (or C if the
`-C' switch was used) program, compiled in the usual manner,
and fully debuggable provided that the `-g' switch is used on
the
gnatlink
command (or `-g' is used in the
gnatmake
command itself).
The name of this package containing the main program is
`b~xxx.ads/adb' where xxx is the name of the Ada main unit given
in the gnatbind command, and you can edit and debug this file in the
normal manner. You will see a series of calls to the elaboration
routines of the packages, and you can debug these in the usual manner,
just as if you were debugging code in your application.
- `How can I debug the Ada run-time library ?'
- The run time distributed in binary versions of GNAT hasn't been
compiled with debug information. Thus, it needs to be recompiled
before you can actually debug it.
The simplest is to recompile your application by adding the switches
`-a' and `-f' to the gnatmake
command
line. This extra step is then no longer required, assuming that you
keep the generated object and ali files corresponding to the GNAT run time
available.
Another possibility on Unix systems is to use the file `Makefile.adalib'
that can be found in the adalib directory of your GNAT installation and
specify e.g `-g -O2' for the `CFLAGS' switches.
- `The GPS main window is not displayed'
- If when launching GPS, nothing happens, you can try to rename the `.gps'
directory (see 16.3 Files) to start from a fresh set up.
- `My project have several files with the same name. How can I import it in GPS?'
- GPS's projects do not allow implicit overriding of sources file, i.e.
you cannot have multiple times the same file name in the project
hierarchy. The reason is that GPS needs to know exactly where the file
is, and cannot reliably guess which occurrence to use.
There are several solutions to handle this issue:
- Use scenario variables in the project
The idea is that you define various scenarios in your project (For
instance compiling in "debug" mode or "production" mode), and change
the source directories depending on this setup. Such projects can be
edited directly from GPS (in the project properties editor, this is
the right part of the window, as described in this documentation). On
top of the project explorer (left part of the GPS main window), you
have a combo box displayed for each of the variable, allowing a simple
switch between scenarios depending on what you want to build.
- Use extending projects
These projects cannot currently be created through GPS, so you will
need to edit them by hand. See the GNAT user's guide for more
information on extending projects.
The idea behind this approach is that you can have a local overriding of some
source files from the common build/source setup (if you are working
on a small part of the whole system, you may not want to have a complete
copy of the code on your local machine).
- Put all duplicate files in the same project
There is one specific case where a project is allowed to have duplicate source
files: if the list of source directories is specified explicitely. All
duplicate files must be in the same project. With these conditions, there is
no ambiguity for GPS and the GNAT tools which file to use, and the first
file found on the source path is the one hidding all the others. GPS only
shows the first file.
You can then have a scenario variable that changes the order of source
directories to give visibility on one of the other duplicate files.
This document was generated
by Mail Server on November, 9 2003
using texi2html