16. Environment

16.1. Command Line Options

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
   -XVAR=VALUE         Specify a value for a scenario variable
   --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

   --config=file       Specify the configuration file (.cgpr) to load
   --autoconf          Generate .cgpr automatically if needed
   --configdb=dir      Extra directories for gprconfig

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 :command`+line` prefix, e.g. gps +40 source.adb.

tools_host corresponds to a remote host’s nickname as defined in Setup the remote servers.

By default, files you specify on the command line can have absolute or relative pathnames. If you prepend a filename with the = character, GPS looks for the file in the source search path of the project. If you do not specify a project on the command line, GPS tries to find one. Otherwise, it displays the welcome dialog.

16.2. Environment Variables

You can set the following environment variables to override default settings in GPS:

  • GPS_HOME

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

  • GPS_DOC_PATH

    Sets the search path for the documentation. See Adding documentation.

    If you installed GPS in a directory different from that of the GNAT compiler, you need to set this variable for GPS to find the documentation for GNAT. In the case of the compiler documentation, for example, the gps_index.xml file installed with GPS assumes GPS_DOC_PATH points to the directory containing gnat_ugn.html, so it should contain gnat_prefix/share/doc/gnat/html.

  • GPS_CUSTOM_PATH

    Contains a list of directories to search for custom files. See Customizing through XML and Python files for more details.

  • GPS_CHANGELOG_USER

    Contains the user and e-mail to use in the global ChangeLog files. The convention is to have two spaces between the name and the e-mail, such as “John Does <john.doe@home.com>”

  • GPS_STARTUP_PATH

    Contains the value of the PATH environment variable just before GPS was started. GPS uses this to restore the proper environment before spawning applications independently of what directories it needs to put into its own path.

  • GPS_STARTUP_LD_LIBRARY_PATH

    Same as GPS_STARTUP_LD_LIBRARY_PATH but for the LD_LIBRARY_PATH variable.

  • GPS_PYTHONHOME

    If set, the Python interpreter looks for libraries in the subdirectory lib/python<version> of the directory specified.

  • GNAT_CODE_PAGE

    You can set this variable to CP_ACP or CP_UTF8. It 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, it may be necessary to set this variable to CP_ACP which is the default Windows ANSI code page.

  • GPS_ROOT

    Overrides and hardcodes the default root installation directory. You usually do not need to set this variable unless you are a GPS developer in unusual circumstances. GPS finds all its resource files (e.g., images, plugins, and xml files) from this variable, so setting it to an incorrect value will cause GPS to misbehave.

  • GPS_MEMORY_MONITOR

    If set, GPS adds special code on every allocation and deallocation to make it possible to check where the largest amount of memory is allocated using the GPS.debug_memory_usage Python command. Setting this variable will slow GPS down.

16.3. Files

  • $HOME/.gps

    GPS state directory. Defaults to C:.gps under Windows systems if the HOME or USERPROFILE environment variables are not defined.

  • $HOME/.gps/log.txt

    Log file automatically created by GPS. When GPS is running, it creates a file log.<pid>, where <pid> is the GPS process id, so multiple GPS sessions do not clobber each other’s log. In case of a successful session, this file is renamed to log when exiting; in case of an unexpected exit (when bug box is displayed) the log file retains its original name. The name of the log file is configured by the traces.cfg file.

  • $HOME/.gps/aliases

    File containing user-defined aliases (see Defining text aliases).

  • $HOME/.gps/plug-ins

    Directory containing files with user-defined plugins. GPS loads all XML and Python files found under this directory during start up. Create or edit these files to add your own menu and/or tool-bar entries in GPS or to define support for new languages. See Customizing through XML and Python files and Adding support for new languages.

  • $HOME/.gps/key_themes/

    Directory containing user defined key themes (XML files). These themes are loaded through the key shortcuts editor.

  • $HOME/.gps/keys6.xml

    Contains all key bindings for the actions defined in GPS or custom files. This file only contains the key bindings overridden through the key shortcuts editor (see The Key Shortcuts Editor).

  • $HOME/.gps/gps.css

    Configuration and theme file for gtk. This file can change specific aspects of the look of GPS. Its contents overrides any other style information set by your default gtk+ theme (as selected in the Preferences dialog) and GPS’s prefix/share/gps/gps.css file.

  • $HOME/.gps/perspectives6.xml

    Desktop file in XML format (created using the File ‣ Save More ‣ Desktop menu). It is loaded automatically if found.

  • $HOME/.gps/locations.xml

    List of locations GPS previously edited. It corresponds to the history navigation (Navigate ‣ Back and Navigate ‣ Forward) menus.

  • $HOME/.gps/properties.db

    Stores file-specific properties across GPS sessions. In particular, it contains the encoding to use for files where the default encoding is not appropriate.

  • $HOME/.gps/histories.xml

    Contains the state and history of combo boxes (for example, the Build ‣ Run ‣ Custom… dialog).

  • $HOME/.gps/targets.xml

    Contains the build targets defined by the user.

  • $HOME/.gps/preferences.xml

    Contains all the preferences in XML format, as specified in the preferences menu.

  • $HOME/.gps/traces.cfg

    Default configuration for system traces. These traces are used to analyze problems with GPS. By default, they are sent to the file $HOME/.gps/log.<pid>.txt.

    This file is created automatically when the $HOME/.gps/ directory is created. If you remove it manually, it is not recreated the next time you start GPS.

  • $HOME/.gps/startup.xml

    List of scripts to load at startup as well as additional code that needs to be executed to set up the scripts.

  • $HOME/.gps/activity_log.tmplt

    Template file used to generate activities’ group commit-log and patch file’s header. If not present, the system wide template (see below) is used. The set of configurable tags are described into this template.

  • prefix

    Prefix directory where GPS is installed, e.g /opt/gps.

  • prefix/bin

    Directory containing the GPS executables.

  • prefix/etc/gps

    Directory containing global configuration files for GPS.

  • prefix/lib

    Directory containing the shared libraries used by GPS.

  • prefix/share/doc/gnat-gps/html

    GPS looks for all the documentation files under this directory.

  • prefix/share/doc/gnat-gps/examples

    Directory containing source code examples.

  • prefix/share/doc/gnat-gps/examples/language

    Directory containing sources showing how to provide a shared library to dynamically define a new language. See Adding support for new languages.

  • prefix/share/doc/gnat-gps/examples/tutorial

    Directory containing the sources used by the GPS tutorial.

    See gps-tutorial.html.

  • prefix/share/gps/support

    Directory containing required plugins for GPS that are automatically loaded at startup.

  • prefix/share/gps/plug-ins

    Directory containing files with system-wide plugins (XML and Python files) that are loaded automatically at start-up.

  • prefix/share/gps/library

    Directory containing files with system-wide plugins (XML and Python files) that are not loaded automatically at startup but can be selected in the Plugins section of the preferences editor dialog.

  • prefix/share/gps/key_themes

    Directory containing the predefined key themes (XML files). These can be loaded through the Key shortcuts editor.

  • prefix/share/gps/gps-splash.png

    Splash screen displayed by default when GPS is started.

  • prefix/share/gps/perspectives6.xml

    Description of the default desktop that GPS uses when the user has not defined any default desktop and no project specific desktop exists. You can modify this file if needed, but keep in mind that this will impact all users of GPS sharing this installation. The format of this file is the same as $HOME/.gps/perspectives6.xml, which can be copied from your own directory if desired.

  • prefix/share/gps/default.gpr

    Default project used by GPS, which can be modified after installation to provide defaults for a given system or project.

  • prefix/share/gps/readonly.gpr

    Project used by GPS as the default project when working in a read-only directory.

  • prefix/share/gps/activity_log.tmplt

    Template file used by default to generate activities’ group commit-log and patch file’s header. This file can be copied into a user’s home directory and customized (see above).

  • 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 encounter a bug, please send it to mailto:report@adacore.com or use GNATtracker 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 needed, and/or a scenario describing the actions performed to reproduce the problem as well as listing all the tools (e.g debugger, compiler, call graph) involved.

The files $HOME/.gps/log.txt may also bring some useful information when reporting a bug.

If GPS generates a bug box, the log file is kept under a separate name ($HOME/.gps/log.<pid>.txt so 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.

GPS crashes on some GNU/Linux distributions at start up

Look at the ~/.gps/log.<pid>.txt 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 failed

it means either that there is a conflict with ~/.local/share/mime/mime.cache, in which case removing this file solves this conflict, or that you need to install the shared-mime-info package on your system.

Non-privileged users cannot start GPS

If you have originally installed GPS as root and can run GPS successfully, but normal users cannot, 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.xml and changing the name of the fonts, e.g replacing 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 Debug ‣ Initialize menu), it is usually because the underlying debugger (gdb) cannot be launched properly. To verify this is the problem, try to launch the gdb command from a shell (i.e., outside of GPS). If you cannot launch gdb from a shell, it usually means you are using the 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 wait a little longer, since some communications between GPS and gdb can take significant time to finish. If GPS is still not responding after a few minutes, you can usually get control back in GPS by either typing Ctrl-C in the shell where you have started GPS, which should unblock it. If that does not work, kill the :program:`gdb process launched by GPS using ps and kill or the top command under Unix

and the Tasks view 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 the -g switch is used on the gnatlink command (or ;command:-g is used in the gnatmake command).

The name of the package containing the main program is b~xxx.ads/adb where xxx is the name of the Ada main unit specified in the gnatbind command. Edit and debug this file in the usual manner. You will see a series of calls to the elaboration routines of packages. 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 has not been compiled with debug information, so it needs to be recompiled before you can debug it.

The simplest way is to recompile your application and add the switches -a and -f to the gnatmake command line. This extra step is only required to be done once assuming 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, which is 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, 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 files, so you cannot have the same filename multiple times in the project hierarchy. This is because GPS needs to know exactly where the file is and cannot reliably guess which occurrence to use.

There are several ways 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. Under these conditions, there is no ambiguity for GPS and the GNAT tools as to 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 to one of the other duplicate files.

Use scenario variables in the project

Here, you define various scenarios in your project (for example compiling in “debug” mode or “production” mode) and change source directories depending on the scenario. Such projects can be edited directly from GPS (in the project properties editor, on the right part of the window, as described in this documentation). On top of the Project view (left part of the GPS main window), a combo box is displayed for each variable, allowing you to switch between scenarios depending on what you want to build.

Use extended projects

These projects cannot currently be created through GPS, so you 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 (e.g., 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 :menuselect`System->Preferences->Keyboard` (or launch :program: gnome-keyboard-properties).

Select the Layout tab and click on Layout Options. Then click twice on Using space key to input non-breakable space character, select Usual space at any level, and then close the dialogs.

File associations or icons disappear or misbehave under Windows

Sometimes file associations get redefined under Windows and no longer behave as a GPS user expects (for example, Ada source files become associated with a stock file icon or double-clicking on a project file opens it like a regular text file.) You may be able to restore the expected behavior by reapplying the associations performed during GPS installation. To do this, locate the file registry-gps-version.reg in the root of your GPS installation, and double-click it. Then confirm that you want to apply it in the dialog that appears.

Copy/Paste operations crash GPS running on a forwarded X11 display

It is possible to run GPS on a remote machine using the X11 display forwarding feature of ssh. But a copy/paste operation could cause GPS to crash if untrusted forwarding (ssh -X) is used. Use the ssh -Y option or the ForwardX11Trusted directive in ssh_config to use trusted X11 forwarding and avoid the GPS crash.

Working with Xming

Some old versions of Xming (such as 6.9.0.31) have an issue in that they create “transient” windows larger than the application requests, and do not allow the user to resize these windows. To circumvent this, we have added a command line switch to tell GPS not to store the window sizes and positions: activate this by launching GPS with --traceoff=STORE_WINDOW_POSITIONS.

Buttons placed in dialogs’ header bars or missing with GNOME 3.12+

GNOME 3.12+ override the Gtk settings set by GPS, including the ‘DialogsUseHeaders’ setting, which has for effect to display the buttons at the top of dialogs. This leads to some problems with GPS and sometimes some buttons are missing on some dialogs (e.g: Add button in the Aliases editor). You can run this command from the terminal to force GNOME to disable this setting: gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/DialogsUseHeader':<0>}"

Floating windows are openened in fullscreen on MacOS Sierra

On MacOS Sierra, when GPS is in fullscreen, all the floating windows opened from GPS (e.g: Edit ‣ Preferences…) are opened in fullscreen too by default. This behavior can be disabled by setting the Prefer tabs when opening documents to Manually in the Dock section of the MacOS Sierra’s System Preferences.