The command line options are:
Usage:
gps [options] [-Pproject-file] [[+line] source1] [[+line] source2] ...
Options:
--help Show this help message and exit
--version Show the GPS version and exit
--debug[=program] Start a debug session and optionally load the
program with the given arguments
--debugger debugger Specify the debugger's command line
--hide Hide GPS main window
--host=tools_host Use tools_host to launch tools (e.g. gdb)
--target=TARG:PRO Load program on machine TARG using protocol PRO
--load=lang:file Execute an external file written in the
language lang
--eval=lang:file Execute an in-line script written in the
language lang
--readonly Open all files in read-only mode
--server=port Start GPS in server mode, opening a socket on the
given port
--tracelist Output the current configuration for logs
--traceon=name Activate the logs for a given module
--traceoff=name Deactivate the logs for a given module
--tracefile=file Parse an alternate configuration file for the logs
Source files can be absolute or relative pathnames.
If you prepend a file name with '=', this file will be
searched anywhere on the project's source path
To open a file at a given line, use the '+line' prefix, e.g.
gps +40 source.adb
`tools_host` corresponds to a remote host's nickname as defined in
:ref:`Setup_the_remote_servers`.
The following environment variables can be set to override some default settings in GPS:
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.
Set the search path for the documentation. Adding New Help Files.
Contains a list of directories to search for custom files. See Customizing through XML and Python files for more details.
Contains the user and e-mail to use in the global ChangeLog files. Note that the common usage is to have two spaces between the name and the e-mail. Ex: “John Does <john.doe@home.com>”
Contains the value of the PATH environment variable just before GPS was started. This is used by GPS to restore the proper environment before spawning applications, no matter what particular directories it needed to set for its own purpose.
Same as GPS_STARTUP_LD_LIBRARY_PATH but for the LD_LIBRARY_PATH variable.
If set, GPS will add special code on every allocation and deallocation, thus slowing things down a bit, that makes it possible to check where the biggest amount of memory is allocated, through the GPS.debug_memory_usage python command.
If set, the Python interpreter will look for libraries in the subdirectory lib/python<version> of the directory contained in GPS_PYTHONHOME.
This variable can be set to CP_ACP or CP_UTF8 and is used to control the code page used on Windows platform. The default is CP_UTF8 to support more languages. If file or directory names are using accents for example it may be necessary to set this variable to CP_ACP which is the default Windows ANSI code page.
Override and hardcode the default root installation directory. This variable should in general not be needed, except by GPS developers, in some rare circumstances. GPS will find all its resource files (e.g. images, plug-ins, xml files) from this root prefix, so setting GPS_ROOT to a wrong value will cause GPS to misbehave.
The current version of GPS on Mac OS X requires an X11 server. Such a server is distributed with Mac OS X Panther and Mac OS X Tiger.
Additionally, if you are launching GPS from a standard Terminal, you need to specify the display on which to launch GPS, by typing:
export DISPLAY=:0
before launching GPS.
Note: GPS does not support files with line endings in CR.
GPS state directory. Defaults to C:\.gps under Windows systems if HOME or USERPROFILE environment variables are not defined.
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.
File containing the user-defined aliases (Defining text aliases).
Configuration and theme file for gtkrc. This file can be edited to activate gtk+ specific aspects, or change the look of GPS in some measure. Mostly, everything can be done through the standard GPS preferences, but this file can be used to get access to the old GPS preference “Dynamic Key Binding”. This preference activated a gtk+ behavior were key shortcuts for menu can be changed by simply pressing the appropriate key combination when the mouse is over that menu. It has various dangereous aspects and is not fully supported by GPS, so was removed as a preference, but you can add the following line in gtkrc to get this back:
gtk-can-change-accels=1
Contains the state and history of combo boxes (e.g. the Run->Custom... dialog).
Contains the build targets defined by the user.
Contains all the preferences in XML format, as specified in the preferences menu.
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 the $HOME/.gps/ directory is created. If you remove it manually, it won’t be recreated the next time you start GPS.
This directory contains the sources used by the GPS tutorial.
See gps-tutorial.html.
Default image displayed in the top right corner of GPS when GPS is idle.
Animated image displayed in the top right corner of GPS to indicate that actions (e.g compilation) are on going. If you remove this file, the idle image (gps-animation.png) will always be displayed.
Splash screen displayed by default when GPS is started.
This is the description of the default desktop that GPS uses when the user hasn’t defined his own default desktop and no project specific desktop exists. You can modify this file if you want, knowing that this will impact all users of GPS sharing this installation. The format of this file is the same as $HOME/.gps/perspectives.xml, which can be copied from your own directory if you wish.
Default project used by GPS. Can be modified after installation time to provide useful default for a given system or project.
If you would like to make suggestions about GPS, or if you encountered a bug, please report it to mailto:report@gnat.com if you are a supported user, and to mailto:gps-devel@lists.act-europe.fr otherwise.
Please try to include a detailed description of the problem, including sources to reproduce it if possible/needed, and/or a scenario describing the actions performed to reproduce the problem, as well as the tools (e.g debugger, compiler, call graph) involved.
The files $HOME/.gps/log may also bring some useful information when reporting a bug.
In case GPS generates a bug box, the log file will be kept under a separate name ($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.
This section addresses some common problems that may arise when using or installing 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.
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).
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.
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 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:
Put all duplicate files in the same project
There is one specific case where a project is allowed to have duplicate source files: if the list of source directories is specified explicitly. All duplicate files must be in the same project. With these conditions, there is no ambiguity for GPS and the GNAT tools which file to use, and the first file found on the source path is the one hiding all the others. GPS only shows the first file.
You can then have a scenario variable that changes the order of source directories to give visibility on one of the other duplicate files.
Use scenario variables in the project
The idea is that you define various scenarios in your project (For instance compiling in “debug” mode or “production” mode), and change the source directories depending on this setup. Such projects can be edited directly from GPS (in the project properties editor, this is the right part of the window, as described in this documentation). On top of the project view (left part of the GPS main window), you have a combo box displayed for each of the variable, allowing a simple switch between scenarios depending on what you want to build.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).
GPS is very slow compared to previous versions under unix (GPS < 4.0.0)
GPS versions 4.x need the X RENDER extension when running under unix systems to perform at a reasonable speed, so you need to make sure your X server properly supports this extension.
Using the space key brings the smart completion window under Ubuntu
This is specific to the way GNOME is configured on Ubuntu distributions. To address this incompatibility, close GPS, then go to the GNOME menu System->Preferences->Keyboard (or launch gnome-keyboard-properties).
Select the Layout tab, click on Layout Options. Then click twice on Using space key to input non-breakable space character and then select Usual space at any level and then close the dialogs.
GPS crashes on some GNU/Linux distributions at start up
Look at the ~/.gps/log.xxx file and if there is a message that looks like:
[GPS.MAIN_WINDOW] 1/16 loading gps-animation.png [UNEXPECTED_EXCEPTION] 1/17 Unexpected exception: Exception name: CONSTRAINT_ERROR _UNEXPECTED_EXCEPTION_ Message: gtk-image.adb:281 access check failedThen it means there is a conflict with ~/.local/share/mime/mime.cache. Removing this file will solve this conflict.